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Ch. 1.1: C Package Description 


1.1 C PACKAGE DESCRIPTION 


The Chameleon 32 C Compiler System provides a complete 
development environment for C programming. The C 
Compiler is a complete implementation of Kernighan and 
Ritchie C, and includes the following features: 

• C shell 

• vi style editor 

• Linker 

• Assembler 

• Disassembler 

• Librarian 

The program editing functions are also accessible via 
softkeys, for easy program development. The Chameleon 32 
C Shell controls all C activities using a command line 
interface. 

The Chameleon 32 provides a multi-tasking operating 
system, page display system, custom keyboard, and color 
display for a powerful development environment which is 
familiar to UNIX and PC C language programmers. With the 
multi-tasking system, you can edit a program, compile a 
second program, and run a third program simultaneously. 

Note If you are unfamiliar with the use of the Chameleon 32 

keyboard or the concept and use of pages, refer to the 
Chameleon 32 User’s Guide, Chapter 3: Using the Chameleon 
32. 

Libraries are provided for UNIX compatible standard I/O (file 
I/O, memory access). There are also protocol-specific 
libraries, which include: 

• BOP 

• HDLC 

• SDLC 

• LAPD 

• Analysis 

• Async 

• BSC 

• Basic Rate Interface 

• Primary Rate Interface 

Libraries are also included for floating point math and window 
interface functions. 
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Ch. 1.1: C Package Description 


Compatibility with 
other Systems 


C RIe Upload and 
Download To/From 
a Host Computer 


Run Time 
Environment 


The Chameleon 32 C package is compatible with MS-DOS 
version 2.x. 

C programs developed on other hosts (such as VAXes or 
PCs) can be compiled and run without change on the 
Chameleon 32 if they use UNIX style calls to access console 
and file I/O devices. Programs developed on the Chameleon 
32 that use the same facilities can also be compiled and run 
on other hosts. 

Programs developed on a Chameleon 32 that access the 
Protocol Specific I/O libraries will not run on another 
computer, unless an equivalent protocol specific library is 
developed for that computer’s hardware. Similarly, C 
programs which rely on special system facilities of other 
computers may not be portable to the Chameleon 32 without 
modification. 


Chameleon 32 file upload and download functions may be 
used to transfer C source files between the Chameleon 32 
and other computers. Program code must be linked with 
Chameleon 32 system interface and library code to make 
executable tasks. This means that executable and object 
code files cannot be transferred from other computers to the 
Chameleon 32. 

In the past, test instruments did not offer convenient high level 
language development environments. As a result, present 
users would like to be able to perform program development 
on host computers, and then download programs to the test 
instrument for execution. Due to various portability issues 
described above, functional testing of programs can only be 
done in the test instrument. The Chameleon 32 allows 
download of program source code from a host, and, in 
addition, offers a fast, powerful, complete and easy to use 
stand alone development environment that is familiar to UNIX 
and PC C programmers. 


There are two types of user programs (analysis and 
simulation). Since the run time environment is different for the 
two types, a user program can only be executed in the same 
environment in which it was compiled and linked. 
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Each user program is a separate task with its own default 
page. The shell is responsible for starting the task, assigning 
its default page and killing it upon termination. 

Run flies can be loaded and executed from the development 
system shell. An additional selection of User Task can be 
made (in the Main Menu) to select all files that can be 
executed (ON/OFF). Turning off a task (or using the KILL 
command) will close the task’s page. 

User programs interact with the Chameleon 32 software 
through libraries. The Libraries include: 

• I/O library (for standard console I/O, device access, 
memory and file manipulation), 

• Protocol specific libraries 

• Library to support acquisition buffer activities 

These libraries are described in Appendix B. 
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Ch. 1.2; Loading C 


1.2 LOADING THE C PACKAGE 

Introduction This section gives you brief instructions for loading the C 

Development System. If you need additional information about 
booting and configuring the Chameleon 32, refer to the 
Chameleon 32 User’s Guide, Chapter 3. 

To load the C Development System, do the following: 

1 . Power up and boot the Chameleon 32. 

2. The main configuration page should appear as shown in 
Figure 1.2-1. If this menu is not displayed, move the 
arrow cursor to Setup Mode and press F1 Menu. 



Figure 1 .2-1 : Configuration Page (Menu Setup Mode) 


3. Move the red arrow cursor to the C Development 
System parameter at the bottom of the screen. (If this 
parameter does not appear, your C package is not 
installed.) 

4. Press F2 On. 
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5. Press Go. The message Loading C-Sheil appears in 
the upper right corner of the Configuration page. 

The C Shell banner appears at the bottom of the screen 
and the Applications Selection page is displayed. 

6. To use the C Shell page, press Select until the C Shell 
banner is highlighted (active). You can then use the 
keys listed in the table below to change the size of the C 
Shell page. 


KEY 

FUNCTION 

Move t 

Moves the page banner upward one line at a time (increases the size 
of the page). 

Move i 

Moves the page banner downward one line at a time (decreases the 
size of the page). 

Scroll t 

Scrolls the data displayed in the page upward one line at a time. 

Scroll i 

Scrolls the data displayed in the page downward one line at a time. 

Shift Scroll t 

Scrolls the data displayed in the page upward the number of lines 
displayed in the page. 

Shift Scroll i 

Scrolls the data displayed in the page downward the number of lines 
displayed in the page. 

Shift Hide Page 

Hides the active page so that the banner is no longer visible on the 
screen (the application continues to run). 

Show Page 

Displays a page that has been hidden with Shift Hide Page. 

Replace 

Replace the active page with one that has been hidden using Shift 

Hide Page. 

Shift Move T 

Displays the page in a special full-screen mode referred to as Blow 
Mode (indicated by the letter B on the top left side of the banner). 

Otfier pages cannot be accessed when the active page is in Blow 

Mode. Shift Move t again disables Blow Mode, and returns the 
screen to its previous state. 
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The hardware and protocol are configured from your C 
program. Refer to the appropriate section for a 
description of the available functions: 


C Library Section 5.2 

Window Interface Functions Section 5.4 

Math Library Section 5.5 

Aux Serial Port 2 Functions Section 5.7 

Common Library Features Appendix B.1 

Bit-Oriented Protocol (BOP) Library Appendix B.2 

LAPO Library Appendix B.3 

HDLC Library Appendix B.4 

SDLC Library Appendix B.5 

Basic Rate Interface Library Appendix B.6 

BSC Library Appendix B.7 

Primary Rate interface Library . . . Appendix B.8 

Async Library Appendix B.9 

Analysis Library Appendix B.10 


Section 1 .3 contains a short tutorial to acquaint you with 
the Chameleon 32 C compiler and editor. 

Chapter 2 contains a description of C Shell usage and 
shell commands. 


7. To turn the C Development System off, use one of the 
following methods: 

a. At the C Shell prompt % , enter the command: 

%exit < RETURN > 

b. Select the Configuration page and press F10 Exit. 
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Executing 

C Applications There are two ways to execute a C program that has been 

compiled on the Chameleon 32: 

• You can run it from the C Shell. To use this method, the 
C Development System must be installed on the 
Chameleon 32. Refer to Section 2.1 for more 
information. 

• You can run it from the Applications Selection menu. 
You must use this method to execute a C application in 
the following cases: 

^ To run a C program on a Chameleon 32 that does 
not have the C Development system installed 

> To run a C program on a Chameleon 20. The 
Chameleon 20 C Run-Time module must be 
installed on the Chameleon 20 in order to do this. 

In addition, this method enables you to include your C 
application in your configuration file, so that the program 
can be executed automatically when the configuration file 
is loaded. This procedure is described below. 


To execute a C application from the Chameleon 32 or 
Chameleon 20 Applications Selection menu, do the following: 

1. Compile the C program on a Chameleon 32. See 
Chapter 2.2 for compiler syntax. 

2. The application file name must have the extension .exe. 

3. Copy the file to the hard disk of the Chameleon on which 
you want to run the application. The directory 
determines when the application will be displayed in the 
Applications Selection menu, using the conventions 
described below. 

To have the program appear in the Monitoring window of 
the Applications Selection menu, copy the program to: 

a:\tekelec\analysis\xxxx 

xxxx is one of the sub-directories of analysis. If copied 
to a:'^ekelec^nalysis'^pl, the application is displayed in 
the Monitoring window for ail protocols. 
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If the application is copied to a protocol sub-directory of 
SL'^ekelec^nalysis, the application is displayed in the 
f/lonitoring window only when the Chameleon is 
configured for that protocol. For example, if the 
application resides in a:'^ekelec'^nalysi$\x25, it appears 
in the Monitoring window only when X.25 is the selected 
protocol. 

To have the program appear in the Simulation window of 
the Applications Selection menu, copy the program to: 

A:\tekelec\simui\xxxx 

xxxx is one of the sub-directories of simul. If copied to 
a:'^ekelec\simul, the application is displayed in the 
Simulation window for all protocols. 

If the application is copied to a protocol sub-directory of 
a:'^ekelec\simul, the application is displayed in the 
Simulation window only when the Chameleon is 
configured for that protocol. For example, if the 
application resides in a:\tekelec\simuN(25, it appears in 
the Simulation window only when X.25 is the selected 
protocol. 

Notes Only applications copied to a:\feke/ec\ana/ys/s\appA can 

be started on Ports A + B on Chameleon 32 Dual Port 
machines. Applications in all other directories must be 
started on each port independently. 

Applications developed for the Chameleon 20 use Port A 
only, since Dual Port is not available. 

4. In the main configuration menu, set up the Chameleon 
port for the mode of operation (Monitor or Simulate) and 
protocol appropriate for the C application. 


5. Press Go. This displays the Applications Selection 
menu, with the C application name displayed in the 
window according to the conventions described in step 3. 


6. Move the red arrow cursor to the application name and 
press the function key that starts it on the appropriate 
port (FI Load A, F2 Load B, F3 Load AB). 


7. Press Go to start the application. 
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Programming 

Notes: When running a C application from the Applications Selection 

menu, the Chameleon automatically opens a window for the 
application when it is started and closes the window when the 
application is stopped. This is similar to running the program 
from the C Shell in background mode, using the syntax: 

%progname& 

See page 2.1-5 for more information about using & 
(background mode) in the C Shell. 

When using the Applications Selection menu, a pointer to the 
application file name is passed to argv[0] and a pointer to the 
port selected by the user is passed to argv[1]. This is 
equivalent to executing a program from the C Shell using the 
convention: 

j 

%progname A 
%progname B 
%progname AB 

This information can then be used in the C application to 
initialize and access the appropriate port(s) using the protocol 
library functions. 

In order to exit from the application properly, use the function 
onexit. This function enables you to finish your program when 
the user stops the application from the Applications Selection 
menu. See page 5.2-37 for more information. 
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1.3 C PROGRAMMING TUTORIAL 


Introduction This section contains a brief tutorial that introduces you to the 

process of developing programs in the Chameleon 32 C 
environment. In the tutorial, you write a short program that 
causes the Chameleon 32 to transmit a short message. 

C Program 

Development Figure 1.3-1 illustrates the steps required to develop 

programs using the Chameleon 32 C package. The chapter 
that contains more information about each facility is also 
indicated. 



Source Program 
(file.c} 


Ch. 2.1 .Shell 
Ch. 6: vi Editor 


Object Program 
(file.of 


Ch. 2J2: Compiler Usage 
Ch. 4: Compiler 
Ch. 23: Disassember 


System Library 
and Other 
Object Programs 


Ch.23: Linker Usage 
Ch. 5: Library Commands 
App. B: Tekelec C Libraries 


Executable 

Object 

(a.out) 


Ch. 2.1 : Shell 


Figure 1 .3-1 : C Development Cycle 


Tutorial The following is a hands-on introduction to the process of 

writing, compiling, and executing a C program. This program 
transmits a short message. 

1 . Boot the Chameleon 32. 

2. Use the port Configuration page to turn the C 
Development System ON, and then press Go. After a 
few seconds, the C Shell page banner should appear at 
the bottom of the screen. 
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Note 


3. Display C Shell page so that the % prompt is visible. 
The login file was executed and put you in the home 
directory (as defined in the login file). 

4. List the files and directories on the hard disk by entering: 

Is < Return > 

5. The list should include a directory called USR\. This 
directory has been provided for your user application 
files (although you do not have to store your files in it.) 

Change to the USR\ directory so that the program you 
write will be saved to this directory. To change 
directories, enter: 

Cd USr < Return > 

6. You will use the vi editor to write a program called 
testl.c. In the command, you will use an ampersand 
(&) to open a separate vi page to enter and edit the 
program. This is referred to as background mode. To 
call up the vi editor in background mode, enter: 

\vl test1 .C & < Return > 

The PATH environment variable will look for vi in the \bin 
directory. If you don’t have a login file you should set 
the path (see SETENV command in Section 2.1). 

The VI banner appears at the bottom of the screen. (If 
this is the first time the vi editor has been used this 
session, you may have to wait a few seconds for the 
banner to appear.) 

7. Display the VI page. 

The cursor is positioned at the top of the screen and 
tildes (—) appear on the other lines. The message 
"testl.c" [New File] appears at bottom of page. 

If there is a window banner at the bottom of the screen, 
you will not be able to see the messages on the bottom. 

8. vl will be in command mode. To enter a program, use 
the insert mode. To change to insert mode, press: 

I (Do not press Return.) 
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The screen does not change appearance or display a 
message to distinguish between command and insert 
mode. 

9. Enter the program that is listed in bold type below. 
Programming remarks have been added for your benefit; 
These appear in non-bold type and do not have to be 
entered. 

Press Return at the end of each program line. Use the 
same spacing and capitalization as shown below. Press 
Tab one or more times to indent. 


#1nclude <cliaB.h> /^Defines constants that Mill be used*/ 

#1nc1ude <stdio.h> 

fdefine GOOO^CRC 0 

Min () 

{ 

initpl (DCE, NRZ« 9600L« FILLFF); /^Initial izes simulation of 

bop library*/ 

printf (•Hit RETURN to transmit frame\n*); 

getchar ( ) ; 

transmit (6000__CRC, •hello", 5); /*Transmits the frame 'hello' 

with a good CRC and 5 as the 
frame length in bytes*/ 

puts ("Transmission completed"); 

} 


10. When the program is completely entered, press Esc to 
return to command mode. 

11. To save the file, enter: 

W < Return > 

A message at the bottom of the screen verifies the 
number of lines and characters entered. 

12. To quit vi, enter: 

:q < Return > 

The VI page disappears, but the C Shell page banner is 
still displayed. 


Tekelec 


1.3-3 


Version 2.2 





Chameleon 32 C Manual 


Ch. 1.3: C Programming Tutorial 


13. Display the C Shell page and the % prompt. 

14. .nIow you are back in the shell and ready to compile and 
link the program, using the cc command, which is in the 
BIN\ directory. To do this, enter: 

cc testl.c -Ibop < Return > 

The -I option calls the library libbop.a . If you entered 
the program correctly, the % prompt is redisplayed. If 
you typed something incorrectly, the errors are 
described on the screen. If there are errors, repeat step 
6 to edit the file using vi, and then repeat step 12 to 
compile and link the corrected program. 

15. To execute the compiled program, at the % prompt, 
enter: 

a.OUt < Return > 

16. The following message appears: 

Hit RETURN to transmit frame 

17. Press a key, the frame will be transmitted, and this 
message displayed: 

Transmission completed 
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2.1 SHELL 

Introduction 


Login File 

Configuration 

File 


TEKELEC 


The Tekelec development sheil provides a command line user 
interface for C development. The shell enables you to run programs 
and contains programs for maintaining files and sub-directories. 

There are a number of built-in shell commands that are ioaded into 
m.emory as part of the shell. Typing a command other than one of 
these built-in shell commands is treated as an attempt to load and 
execute a program. 

Some shell commands are built into the shell and also exist as 
programs. These commands include: cc, cp, rm, and mv. If you 
execute one of these commands from a batch file or make file, the 
program is used. 

Each shell and program has the notion of current directory, so you 
can view and work from different directories simultaneously. 

The login batch file is executed automatically when the shell starts. 
It contains a list of sheil commands and can be modified using the vi 
editor. A default login file is provided. Use the more command to 
view the contents of the login file. If you create a new login file and 
save it, the new login file overwrites the existing login file. 

The loader uses an environment variable called PATH to locate 
programs to execute. The PATH variable is set in the login file on 
the distribution disk. Command line argument passage is 
supported. 


The CONFIG.SYS file is used to configure certain functions of the 
Chameleon 32. This file is located in the /TEKELEC/UTIL directory. 
As the Chameleon is booting, CONFIG.SYS is read by the 
operating system and acted upon based on commands within the 
file. Should this file not exist, default values are assumed and acted 
on. 

CONFIG.SYS supports the following commands: 

BOOT - For the P6 board of the Chameleon 32-plus only, 
this command tells the Chameleon which 
application is to be booted at start-up. 

The valid options are: 

A:\\tekeiec\\util\\stmenu.sys 

(stmenu » standard menu) 

A:\\tekelec\\uti^\stshell.sys 

(stshell = C shell) 
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REM - Remark or Comment. Used primarily for 

documentation of the CONFIG.SYS file itself. All 
other commands on this line are ignored. 

DBGPORT - Location of the Debugger Port. Used to place the 
Debugger Port on the AUX 1 serial port or on the 
Chameleon CRT and keyboard. Also used to turn 
the debugger off. When the Debugger is not 
placed on AUX 1 , this port is availabie for other 
applications uses (See Section 5.7). 

This command takes one operand having the following 

syntax: 

AUX1 - places the debugger on the serial port. The 

default location. 

VT - places the debugger on the CRT/keyboard. 

OFF - turns the debugger off. 


For Chameleons operating over an Ethernet: 

GW - allows you to specify the Internet address of the 

gateway connecting your Chameleon 32 to other 
subnets, using standard decimal dot notation. For 
example: 

192.9.200.104 

IMASK - allows you to specify the Internet mask of the 
Internet if subnet masking is used. For example: 

255.255.255.0 

INET - allows you to specify the Internet address of the 

Ethernet board, using standard decimal dot 
notation. For example: 

192.9.200.102 
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Device Files 


Example. 

The following is an example of what a CONFIG.SYS file might look 
like: 


REM This file is used to place the debugger on 

the 

REM Chameleon 32 CRT and keyboard. 

REM By doing this I may now access AUX 1 via a 

C program. 

DBGPORT VT 


Devices are referred to by file names, using the following 
conventions: 

• .CON a Console 

• .PRT a Printer 

• .AUX a Serial port 2 (unformatted data) 

• .TTY a Serial port 2 (formatted data) 

These names must be in upper case letters. For example: 
shell <.TTY> .TTY 

redirects shell input and output through Serial port 2 and will work 
from a remote terminal. 
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Filename 

Substitution 


The * and [ ] characters can be used for filename substitution, as 

Matches all filenames with .c extension. 

Matches all files named test with any file 
extension. 

Matches filenames containing the letter 
enclosed in the brackets, in this example, x. 


Matches filenames containing the indicated 
letters (logically ORed). In this example, 
filenames with b or g or y. 


[(ch),(te)] Matches filenames containing ch or te. 


Matches filenames with the letters in the 
indicated range, in this example, filenames with 
b, c, d, e, f, or g would be matched 


For example, if a directory contains the following files; 
hello.c testl.c test2.c test2.o testl.o a.out 


described below. 

• 

*.c 

• 

test.* 

• 

[X] 

• 

[bgy] or 


[b.g.y] 

• 

[(ch),(te)] 

# 

[b-gl 


If you use the Is (list files) command as shown below, the resulting 
filenames are listed. 

Is * helloc.c test1 .c test2.c test2.o test1 .0 a.out 

ls*.c hello.c testl.c test2.c 

1st* testl.c test2.c test2.o testl.o 

Is *[o]* hello.c a.out 

Any word enclosed in single or double quotation marks prevents 
filename expansion, or creates a single argument to pass to a 
program. For example: 


% a.out *.c receives: argv[0] 

“a.our 

argv[1] 

“HELLO.C” 

argv(2] 

TESII.C” 

argV[3] 

OL (NULL) 

%a.out ’*.c’ receives: argv[0] 

“a.out” 

argv[l] 

“*.c” 

argv[2] 

OL (NULL) 
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I/O Redirection 


Environmental 

Variables 


The shell supports redirection of standard output and input from any 
command line, as follows: 


< name 
> name 
» name 
>& name 
»& name 


Read the file ’name’ in place of stdin 
Write stdout to the file ’name’ 
Append stdout to the file ’name’ 
Write stderr to the file ’name’ 
Append stderr to the file ’name’ 


The default for stdin is the keyboard. The default, for stdout and 
stderr is the window for the calling program. I/O redirection 
operators and names are not passed to the calling program. 

Built-in shell commands also use I/O redirection operators, for 
example: 

dis filename.o | more Uses shell command more 
Is > filename Redirects file listing to filename 

I/O redirection is available through the system function. The 
following example illustrates this. 

main( ) 

{ char line[ 80 ]; 
system (line, "Is"); 
system (line, "Is > filename”); 

} 


The shell supports environment variable setting (setenv) and 
printing (getenv). These variables are stored internally as a string of 
the form: name=’value’. 

The variable PATH (note upper case) is used by the loader to find 
programs to execute. A typical PATH is: 

’. \bin \user’ 

This command string means first search the current directory (.), the 
\bin directory, and then the \usr directory. If you set a path, you must 
include the period (.) or the current directory will not be searched. 
If no path variable is set, only the current directory is searched. 
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The variable VIINIT is loaded by the editor as it is executed. The 
value of VIINIT may be any valid vi commands to be processed as 
the editor is started. The variables FC and BC (foreground color 
and background color) are used as colors for window creation when 
a program is run as a separate task. 

See the description of setenv and getenv for additional 
information. 

Commands The shell supports the commands listed below. In the syntax 

descriptions, angle brackets (<>) indicate that the field is user 
supplied. Square brackets ([ ]) indicate optional items. 

The following methods can be used to execute more than one 
command in a single command line. 

% a; b; c Executes commands, a, b, and c as if they were 
entered as follows: 

%a 
%b 
% c 

% a & b & c Executes commands a, b, and c as if they were 
entered as follows: 

%a & 

%b& 

%c 

% a I b I c Executes commands a, b, and c as if they were 
entered as follows: 

%a > plpel 
% b < pipe1 > pipe2 
%c < pipe2 

The shell commands are listed in alphabtical order, one command 
per page, on the following pages. 
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& (Background Mode) 


Description 


Syntax 


See Also 
Example 


The ampersand symbol (&) is the command that runs an executable 
file in background mode. When the ampersand is used, a window is 
opened for the task and it is used as stdin and stdout. 

<name> & 

where: name is the filename of an executable file. 

To modify the window color, use the setenv command. The window 
will be closed when the task is killed. 

run (page 2.1-30) 

To run the file named PROG1 in background mode, enter: 

% PROGl & 
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# (Remark) 
Description 

Syntax 

Example 


The # sign enables you to enter a remark that is ignored by the shell. 
The remark is not echoed to the screen. It is useful for inserting 
programmer’s remarks in batch files. 

#[text] 

where; text is the remark you want in the batch file. 

To enter a remark, enter: 

fSetting environment. 
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’ (Echo Text) 

Description 

Syntax 

Example 


The ’ sign enables you to echo text to the screen. It can be used in 
batch files to echo messages or instructions to the screen. 

’[text] 

where; text is the text to echo to the screen. 

To display the message ’Hello out there’, enter: 

%' Hello out there! <RETURN> 

Hello out there! 
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batch 

Description 

Syntax 

Example 


The batch command executes a batch file. A batch file is a file 
which contains a sequence of shell commands. 

If a batch file named login exists on the root directory of either the 
hard or floppy disk, it is automatically executed when the shell is 
launched. 

batch <filename> 

where; filename is the name of the batch file. 

To execute a batch file named startup, enter: 
batch startup 
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cat 


Description 


Syntax 


Example 


Errors 


The cat command prints files to standard output. It is used primarily 
to display the contents of one or more files. 

cat <file...> 

where: file is the name display on the screen. If a single file name 
is specified, the contents of that file is displayed on the screen. 

If two or more files are specified, cat concatenates them in the order 
given and writes the output to the indicated file. 

If the file parameter is not specified cat reads from standard input. 

To display the contents of the file prog1 , enter; 

cat progl 

To concatenate the contents of fiiea and fileb and write the result 
into filec, enter: 

cat fiiea fileb >filec 

File not found: name The file or directory name does not exist. 
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cd 

Description 

Syntax 

Example 


The cd command changes the current sub-directory. 

To determine the names of the sub-directories of the current 
directory, use the Is command. This lists the entries of the current 
directory with sub-directory names followed by a slash {\). 

The root directory is referred to by a back slash (\). 

cd <path> 

where: path is the path name of the sub-directory that you want to 
use. 

To change from the root directory to the USR/ sub-directory, enter: 

cd usr <RETURN> 

To change back to the root directory, enter: 
cd \ 
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cp 

Description 

Syntax 


Example 

Errors 


The cp command copies one or more files into a specified director^'. 
The cp command can be used to make copies of files, rename files, 
or transfer files to a different directory. 

cp <oidfile> <newfiie> 

where: oidfile is the name of the source file and newf ile is the name 
of the new copy of the file. The cp command will not copy a file onto 
itself, therefore a newftle name must be supplied. 

if newfiie already exists, its contents are ovenivritten. If newfile is 
ovenrvritten by the cp command, the original mode and owner are 
preserved. If nev/fiie is a new file, the mode and owner of the 
source file is used. 

The cp command copies one or more files into a different directory, 
using the following syntax: 

cp <file...> <dir/> 

where: file is the name of the file to copy and dir is the name of the 
directory to copy the file into. Note that the directory name is 
followed by a slash (/) to indicate that it is a directory and not a new 
filename. The filenames remain unchanged. 

To make a copy of a file named PROG1 and give the copy the name 
PROG2, enter: 

cp progl prog2 

To copy a file named PROG1 Into USR/ sub-directory, enter: 
cp progl usr/ 

Can’t copy file to itself: name CP was given the same file name 

to copy to as the source file 
name. 

name: not a directory The name of the directory to copy 

to was invalid. 

Can’t open: name The source file does not exist, or 

there is something wrong with the 
disk. 
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ctags 

Description 

Syntax 


ctags is a utility that helps you locate definitions in muitiple C 
program files. It searches specified files and creates a file named 
tags which contains a list of the functions that were found in the 
program files. The fags file can then be used in conjunction with the 
vi editor to quickly locate specific functions in the files you are 
editing. 

ctags files 

where: files are the C program filenames that you want to search 
through. You can use wildcards to specify the files to search. For 
example, this searches all C source files beginning with the name 
test: 


ctags test*.c 

This creates a file named tags which contains the following 
information about the definitions (tags) in the files that were 
searched. 

tag filename String to search for 

You can use the more command to view the contents of the fags file. 


There are two ways to use the tags file with the vl editor: 

1. Use the option when you invoke the vi editor. For example: 
vi -t tagname 

This edits the first file listed in the fags file which contains the 
tag specified by tagname. The cursor is positioned at the first 
occurrence of the tag in the file. 

2. Invoke the vi editor and then use the :tag command. For 
example: 

vi *.c 

:tag tagname 

This first invokes the vi editor to edit all .c files. The :tag 
command then positions the cursor at the first occurrence of 
the specified tag within the files being edited. 
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dump 


Description 

Syntax 

Example 

Errors 


The dump command prints one or more files in hex to standard 
output. 

dump file 

To print the contents of the file named test1 in hex, enter: 
dump test1 

File not found: name The file name does not exist. 
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exit 

Description 

Syntax 

Example 


The exit command exits from the C shell and returns to the 
Chameleon 32 port configuration page. It causes the C shell to no 
longer be active. 

exit 

To return to the Chameleon 32 port configuration page from the C 
shell prompt (%). enter: 

exit 
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format 

Description 

Warning 

Syntax 

Example 


The format command formats a floppy diskette. 

Formatting erases all the data on the disk. Make back up copies 
of files you want to keep before you format. 

format b 

To format the floppy disk, enter: 
format b 

The following message is displayed: 

Do you wish to format the floppy disk B:? (Yes or No) Y <cr> 
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getenv 

Description 

Syntax 


Example 


TEKELEC 


The getenv command prints the string value of all environmental 
variables or of a specified environment variable. Use the setenv 
command to set the value of an environment variable. 

getenv Displays values of all environmental 

variables. 

getenv <name> Displays value of a specified 

environmental variable. 

where: name is the name of the environment variable to print. The 
following variable names are used by the Shell, but up to 20 
variables can be defined by the user. The following variable names 
must be entered in UPPER CASE letters. 


PATH 

Displays the default search path for 
locating files. 

FC 

Displays the foreground color for new 
windows. 

BC 

Displays the background color for new 
windows. 

YEAR 

Displays the global _curr_jear in the 
libraries 

HOME 

Displays a path that is changed to when 
the cd command (with no argument) is 
used. 


To display the current default search path, enter; 

% getenv PATH <RETURN> 

•b: \bin 

To display the foreground color for new windows, enter; 

% getenv FC <RETURN> 
white 
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help 

Desorption 

Syntax 

Example 


The help command displays a list of shell commands and their 
usage. 

help 

% help 
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jobs 

Description 

Syntax 

Example 


TEKELEC 


The jobs command prints job control status, including process id 
(pid), program name, and whether resident or running. 

If running, a program is active and can be killed using the kill 
command. 

If resident, a program is in memory, and when started, is loaded 
from memory and not from disk. 

jobs 

To display the current jobs and their process id numbers, enter: 

% jobs 

[ 0] Running B;\SHELL 
[ 1] Resident B:\BIN\CP 
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kill 


Description 


Syntax 


Example 


The kill command kills a process that is running. It does not remove 
the process from residency. 

kill <pid> 

where: pid is the process id of the program to kill. Refer to the jobs 
command to print pids and other information about programs. 

If you want to view the current jobs, enter: 

jobs 

A display such as the following appears: 

[ 0] Running B:\SHELL 
[ 1] Resident B:\BIN\CP 
[ 2] Riinning B;\USR\PROGl 

This display indicates that PROG1 is running and is assigned 
process id 2. To stop the process but leave PROG1 resident, enter: 

kill 2 
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Is 

Description 


Syntax 


Example 

Error Messages 


The !s command prints a list of files and directories, and information 
about them. If a directory {or drive specifier) is given, the directory 
name, number of files in the directory, and a list of all files in the 
directory is displayed. If a file name is given, matching file names 
are listed. If no file/directory names are given, the contents of the 
current directory is listed. In the absence of a sorting option, names 
are sorted alphabetically. 

In the resulting display, sub-directory names are followed by a 
slash (/). 

is [-L1 [-K] [-S1 [-D] [spec] 

Is options are: 

-L Long listing format. Provides the name, size 

(excluding header information) and date of the file, 
with each file displayed on a separate line. 

-/C Listing is sorted by file extension (kind) 

-S Listing is sorted by size 

-£? Listingis sorted by date of last modification. 

If one of the sorting options is note used, the list is sorted by 
filename. Filename substitution is performed. 

To list the files in the current directory including the date and size, 
enter: 


Is -L 

To list ail entries in the current directory that begin with the letter S, 
enter: 

Is s* 

Unknown option: option An option was given that LS does 

not recognize. 

File not found: name The file or directory names does not 

exist. 

Drive DRIVE: not available The drive is not available. 
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man 

Description 

Syntax 


Example 


The man command displays a named help file for C commands, 
programs, and library functions. 

man <filename> 


w/7ere;filenameisthenameofthe help file. The following help files 
are available; 


Filename Tonic 


anal 

ar 

asynclib 

aux2lib 

bop 

bri 

bsc 

cc 

dis 

egrep 

filefunc 

hdic 

lapd 

Id 

libc 

make 

mathlib 

mlink 

pri 

sdic 

shell 

v120 

vi 

window 


Analysis library 
Librarian 
Async library 
Aux Port 2 library 
BOP library 
BRI library 
BSC library 
compiler 
Disassembler 
egrep 

Low level MS-DOS file functions 
HDLC iibrary 
LAPD library 
Linker 

Standard C library functions 

make command 

Math library 

Multi-Link LAPD library 

PRI library 

SDLC iibrary 

Shell commands 

V.120 library 

vi commands 

Window functions 


To display the help file for the BOP library, enter: 


man bop 
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mkdir 

Description 

Syntax 

Example 

Errors 


The mkdir command creates a sub-directory. If a partial pathname 
is given, mkdir creates the sub-directory in the current directory. 

mkdir <name> 

where: name is the name of the sub-directory you are creating. 
To make a new sub-directory named PROGS, enter: 
mkdir progs 

Can’t create directory: name The directory name already 

exists, or the disk is write 
protected. 
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mkres 

Description 

Syntax 


Example 


The mkres command makes a program RAM resident. Normally, 
any program you execute becomes RAM resident. The mkres 
command enables you to make a program RAM resident without 
running it. It also prints the process id (pid) of the program. 

mkres (-p] <prog> 

where: prog is the filename of the program. 

The -p option indicates that the program cannot be removed from 
memory to satisfy a request for a block of free memory. If the 
memory manager receives a request for a block of free memory 
which it cannot satisfy, it removes the least recently used programs 
until it can satisfy the request. The -p option indicates that the 
program cannot be removed by the memory manager. 

This option is useful for large programs, such as the compiler, which 
take some time to load. 

To make a program named PROG1 resident in RAM, enter: 
mkres progl 
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more 


Description 


Syntax 


Example 


The more command displays the contents of a specified file or pipe, 
one screenful at a time. If the display is longer than a single screen, 
it pauses when the screen is full, and prints the following prompt at 
the bottom of the screen: 

— more — (n%) 

The n% is an integer that indicates the percentage of the file (in 
characters) that has already been read. The percentage is not 
displayed if more is reading from a pipe. 

You have three options for displaying additional text on the screen 
when the — more — prompt appears. These options are: 

• Press Return to display the next line from the file 

• Press the Space bar once to display the next screen 

• Type a number and then press Space bar to display that 
number of lines. For example, to display the next 10 lines, 
enter: 

10 <Spacebai> 
more <file> 

where: file is the name of the file to display. 

If more is redirected to a device other than a terminal, it transmits 
the file. 

To list the contents of the file PROG1 , one screenful at a time, enter: 
more progl 
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mv 


Description The nfiv command moves a file, removing the original copy of the 

file. You can use the command to move the replace an existing file 
with another file or to move files from one directory into another 
directory. 

Syntax mv fiie1file2 Replace file2 with the contents of file1 . 

Both files must already exist. 

mv flies dir Move the specified files from the current 

directory into the specified directory. 

Example To replace the contents of test1 with test2, enter: 

mv test2 testl 

To move all files named test to the parent of the current directory, 
enter: 

mv test* . . 

Where .. specifies the parent of the current directory. 

Errors Can’t copy file to Itself: name MV was given the same file name 

to move to as the source file 
name. 

name: not a directory The name of the directory to 

move to was invalid. 

Can’t open: name The file that is to be moved does 

not exist, or there is a disk error. 
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pwd 

Description 

Syntax 

Example 


The pwd command displays the name of the current directory on 
the screen. 

pwd 

to display the current directory, enter: 

% pwd 
B;\USR\ 
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rm 

Description 

Syntax 

Example 

Errors 


The rm command deletes one or more files from the disk, 
rm <file> [file...] 

where: file is the name of the file to delete. Note that you can delete 
more than one file with a single rm command by listing the 
filenames separated by blank spaces. Filename substitution is 
performed. 

To delete a file named PROG1 , enter: 
rm progl 

To delete all files that have PROG as the first four letters of the 
filename, enter; 

rm prog* 

Usage: rm file... There are no options to rm. 
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rmdir 


Description The rmdir command deletes a sub-directory. You cannot delete a 

sub-directory if it is the current directory. You must be in the parent 
of the sub-directory in order to delete it. The directory must be 
empty before you can delete it. 

Syntax rmdir <name> 

where: name is the name of the sub-directory you are deleting. 

Example To remove the directory named PROGS, enter: 

rmdir progs 

Errors No such directory: name The directory name does not exist or 

the disk is write protected. 
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rmres 

Description 

Syntax 

Example 


The rmres command makes a RAM resident program 
non-resident. 

rmres <pid> 

where: pid is the process id of the program. Refer to the jobs 
command to print pids and other information about programs. 

If you want to view the current jobs, enter; 

jobs 

A display such as the following appears: 

[ 0] Running B:\SHELL 
[ 1] Resident B:\BIN\MORE 
[ 2] Resident B:\BIN\CP 

This display indicates that the more program is resident and is 
assigned process id 1 . To remove the more program from RAM, 
enter: 

rmres 1 

The screen then displays; 

[ 1] Removed B:\BIN\MORE 
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run 

Description 

Syntax 


Note: 

See Also 
Example 


The run command runs a program as a separate process. It loads 
the program, creates a new window for the program’s standard I/O, 
and executes the program. 

run [-XXX] <prog> 

The -XXX option sets the process priority within the range 1 - 230, 
with 230 having the highest priority. The process priority is actually 
the priority given to the MTOS-UX operating system when a task 
is created. The default priority is 100 unless otherwise specified. 

The & character may be used as the last character of a command 
line to indicate ’run’. 

By setting your task’s priority, you can force your task to run by 
taking CPU time from other tasks. For example, the following are 
the process priorities assigned to Chameleon Monitoring 
applications: 

Real Time display 100 

History 200 

Statistics 200 

if your task does only CPU processing (no I/O), it may not allow 
processing time for other applications. If this occurs, you can use 
the MTOSUjX pause function to allow time for other tasks to run. 


& (page 2.1-5) 

To run the program named PROG1 , enter: 
run progl 

A progl banner appears at the bottom of the screen for the I/O of 
the program. 

To run the program named PROG1 with a process priority of 200, 
enter: 

run -200 progl 
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setenv 

Description 

Syntax 


Example 


The setenv command sets an environment variable, 
setenv <name> <’value’> 

where: name is the name of the environment variable and Value’ 
is the string value of name. Note that the value is enclosed in 
quotation marks to protect the string. 

The following variable names are used by the Shell, but up to 20 
variables can be set and used by a user program. The following 
variable names must be entered in UPPER CASE letters. 

Sets the background color for new windows. 
Sets the foreground color for new windows. 
Contains a path to change to if the cd command is 
used without an argument. If no HOME variable is 
found, the path is set to the root. 

Sets the default search path for locating files. 
Sets the global _curr_year in the libraries. 

The available foreground and background colors are: 

• black 

• red 

• green 

• yellow 

• blue 

• magenta 

• cyan 

• white 

To set a path from the current directory (.) to the root directory to the 
BIN sub-directory on the A drive, enter 

setenv PATH a: . ' \bin b: \' 

To set the foreground color to blue, enter: 

setenv FC 'blue' 


BC 

FC 

HOME 


PATH 

YEAR 
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shell 


Description 


Syntax 


Example 


The shell command starts another shell that will do all that the C 
shell does. The other shell can be run in background mode, if 
desired. 

Note: The cd command will not work on all shells, 
shell <name> & 

where: name is the shell name and the & optionally runs the shell 
in background mode. 

To run a shell called newshell in background mode, enter: 
shell newshell & 
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size 

Description 

Syntax 

Example 


The size command prints size information for the different 
segments of object or executable files to standard output. 

size files 

To display the size of an object file names scripts.o, enter; 


size scripts.o 
The resulting display will be; 
text data bss dec 

17590 4384 0 21974 


hex 

55d6 scripts.o 
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time 

Description 

Syntax 

Exampie 


The time command displays the current time as maintained by the 
Chameleon 32 clock. 

time 

To display the current time, enter: 

% time 

23 SEP 1987 02:06:34 
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SHELL ERROR MESSAGES 


Table 2.1-1 lists the Shell error messages and their meanings. 


ERROR 

MESSAGE 

MEANING 

L_FNFERR 

RIe not found. 

L_OPNERR 

Command not found. 


Memory allocation error. 


File read error. 

L_RELERR 

File contains external references. 

L_FMTERR 

File not executable. 

■SQESHI 

Program is currently running. 

ISSSSSflii 

Too many programs currently loaded. 

MBSaSSSiMM 

Tried to restore a non-resident program. 


Could not get semaphore to use loader. 

Ei5s!jB3H 

Command line error. 


Unable to create a task. 

Illlllli^SS SIIhS 31^^ 

Unable to get a new key. 


Out of memory. 

mmmm 

Bad command line syntax. 

1 S_PTYERR 

Priority must be from 1 - 230 


Table 2.1-1 : Shell Error Messages 
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2.2 COMPILER COMMANDS 


Introduction This section describes the compiler commands cc and mcc. 


cc The cc command compiles and links files. The cc command 

runs the compiler mcc and/or the linker Id on the specified 
files depending on the file extension. 

Compiler flags and files with the .c extension (C source files) 
are passed to mcc. Linker flags and files with the .o 
extension (object files) are passed to Id. This includes .o files 
produced from .c files by the compiler. When the cc 
command calls the linker, the proper init code and C system 
library are included automatically. 

The cc command functions as shown in this example: 

cc [flags] [file.c] mcc [flags] [file.c] -IMnclude 

Id [flags] \lib\init.o file.o \lib\libc.a \lib\libm.a 

cc [flags] [file.o] Id [flags] \lib\init.o file.o \lib\libc.a \lib\libm.a 

The compiler commands cc and mcc are described in this 
section, id is described in Section 2.3. Square brackets [ ] 
indicate an optional field; angle brackets < > indicate a user 
specified field. 

The cc command uses the following syntax: 
cc [-c] [flags] [file.c/file.o...] 

The cc fields are: 

-c Compiles only; does not link 

flags Optionally specified flags for Id and mcc as 
summarized below. 

Id flags: -d Debug option. Causes the linker to 

include the names of functions in 
the executable program. 

-Ixxx Library search path. The linker 
automatically searches the path 
MibMibxxxx.a where libxxxx.a is the 
name of the library. 
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-m Prints names and addresses of 

giobais which are included in the 
executable program. Creates 
MAPFILE of globals in program. 
This is a set of symbols and their 
offset from the beginning of the file. 

-o Writes output to specified output 

file (default is a.out). 

-txxx Linker adjusts references wihtin 

program as if program were at hex 
memory location xxx. 


mcc flags: -Ipath Causes the compiler to search the 

specified path for include files. 
Default path is Mnclude. 

-dname Equivalent to inserting #define 
name in the source. 

-dname = value 

Equivalent to inserting #define 
name value in the source. 

-x Trace Mode. Adds calls to the 

debugging routines __debugin as 
each function is entered and 
debugout as each function 
terminates. 


flle.o If an object file is specified, cc calls Id only (links), but 
does not call mcc (compiler). 

file.c If a C sourcefile is specified, cc calls Id (linker) and 
mcc (compiler), unless the -c option is included.. 
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mcc 


Compiler Errors 


mcc is the name of the compiler and compiles one C source 
file at a time. It uses the following syntax: 

mcc [-dname[ = value] ] [-Ipath] [-x] [-IMfile] <flle.c> 
The mcc command fields are: 

•dname Equivalent to inserting #define 

name in the source. . 

•dname rvalue Equivalent to inserting #define 

name value in the source. 

Example: Dtest * 1 is the same as 
#define test 1 in the source file. 

-Ipath Causes the compiler to search the specified 
path for include files. Default path is \include. 

-X Trace Mode. Adds calls to the debugging 

routines debugin as each function is 
entered anS debugout as each function 
terminates. TRe routines shown below are 
the default routines that will print the 
procedure names and the passed 
parameters. These routines can be 
overwritten by user routines. 

debugin(args, format) 
char **args; 
char ^format; 

args Is a pointer to the parameters on the 
stack 

format is a pointer to a printf type format 
string containing the name of the function 
entered and a % conversion for each arg. 

debugout(name) 
char *name; 

name Is a pointer to a string containing the 
name of the fucntlon that is terminating. 

flle.c The C source file name. C source files have 
the file extension .c. The compiler produces 
an object file and assigns the same file name 
as the corresponding C file, but changes the 
extension to .o. 

Refer to section 2.8 for a list of global error codes which can 
be returned by the compiler. 
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2.3 LINKER COMMAND (Id) 

Introduction The Tekelec Linker is similar to the UNIX linker Id. The linker 

takes as input multiple object and library files and creates an 
executable file from them by resolving all external references 
(references to symbols not defined in the file making the 
reference). The user specifies which object files he wants 
loaded and which library files he wants searched. 

The utility program named cc includes the correct libraries and 
initialization code. You will normally use program cc to 
compile and link your user programs. 

The linker must be used even if a program doesn’t contain any 
external references because an object file created by the 
compiler is not executable. 

Symbols defined in the user specified object files will override 
definitions of the same symbol in the libraries because user 
object files are loaded first. Likewise, symbols defined in the 
first libraries in the list override definitions from latter libraries 
(the system library is always read last). A programmer may 
make use of this feature by writing his own versions of system 
library functions (such as ma1 loc for instance) while still using 
other procedures from the library. 

Usage The linker is run from the shell. Linker command syntax is 

shown below. Square brackets [ ] indicate optional fields; 
angle brackets < > indicate user specified fields. 


Id [-V] ['Uib] I'M] [-X] [-Txxx] [-0 output] < objects > [libraries] 


The fields for the Id command are: 

-V Verbose option. Displays the names of the 

functions in each of the object or library files 
specified in the command line. 


-Lllb Library search path. The linker automatically 

searches the path MibMibxxxx.a where libxxxx.a 
is the name of the library. 
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-M 


-X 


-Txxx 


-o output 

objects 


libraries 


For example, to compile prog.c using the libsdic 
(SDLC library), you can use the command: 

id prog.o -isdic 

This causes the same result as entering: 

Id prog.o libMibsdlc.a 

Prints names and addresses of globals which are 
included in the executable program. Writes this 
information to MAPFILE. This is a set of symbols 
and their offset from the beginning of the file. 

Debug option. This option causes the linker to 
include the names of functions in the executable 
program. If the program terminates abnormally 
(dure to a processor exception), a stack dump 
can be printed. Static functions begin with a tilde 
(*) while global functions being with an 
underscore ( ). 


Causes the linker to adjust references within the 
program as if the program was at hex memory 
location xxx. Norrhally, the program is linked as if 
it were based at location zero, and relocation 
information is included so that when a program is 
run, the references may be adjusted for the 
actual memory location. Setting this option also 
prevents this relocation information from being 
included. 

Writes output to a file, where output it the name 
of the output file. The default output file name is 

a. out 

One or more input object files. This must always 
include: 

/lib/init.o 

One or more input libraty files, if not already 
specified with the -Lllb option. 


Tekelec 


2.3-2 


Version 2.5 




Chameleon 32 C Manual 


Ch. 2.3: Linker Command 


Linker Errors 


If an error occurs during the link, the link is aborted and no 
output program is written. Error messages are listed below. 
Also refer to section 2.8 which describes the global error 
codes which can be returned by the linker. 

Usage: Id [-d] [-txxx] [-m] < infile > [-ixxx] [-o outfile] 

Either an invalid link option was specified, or no object or 
library files were given. 

File open error: name 

The object or library file name was not found. Check to 
see that the file name and path name are given correctly 
and that the file actually exists. 

Rie read error: name 

Likely a disk problem. Try a newly formatted disk. 

RIe write error: name 

Either the disk onto which the linker output is being 
written is full, or there is a physical problem with the 
disk. Check to see that adequate space for the output is 
avialable. 

Unable to open output file: name 

Check to see that the disk is not write protected, and 
that the path given for the output, if any, is correct. May 
also be the result of a problem with the disk. 

File format error: name 

The named input file is not in the correct format or has 
been corrupted. Assure that only object files and library 
files are specified. 

Undefined symbol(s): 

The linker found references to function name(s) or global 
variable name(s) for which there is no definition. Make 
sure that the listed globals are actually defined, and that 
references to library functions are spelled correctly. 
Note that a leading underscore ( ) is added to each 
global by the compiler and should* be ignored by the 
user. 

Duplicate name definition: name 

The global name has been defined in more than one 
place. Eliminate or rename one of the 
Tunctions/variables. 
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No name list: file 

RIe is missing symbol table Information. Object files 
nr ust have at least one global name to be linked. 

No string table: file 

RIe is missing its string table, a list of the actual names 
referred to by the symbol table. 


The Unking 

Process The linker examines each argument in the order given. 

Object is always included, while libraries are searched by the 
linker and only those object code modules which are needed 
are actually included in the final executable program. Since 
libraries frequently contain many object code modules, the 
archiver may be used to add an index of global function and 
variable names to the beginning of a library. Using this index, 
the linker can quickly resolve external references, greatly 
speeding the linking process. 

The index, if it exists, is loaded into memory and searched 
repeatedly until either no more undefined names need 
resolving, or a complete pass of the index is made and no 
additional object code modules are extracted. If the library 
does not contain this index, the linker will make only one 
sequential pass through the library, including code modules 
only If they are needed. Therefore, without the index, 
references in the library must refer to object modules which 
appear further into the file. 
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Object File 

Format A.out is the format of the object file that is created by the 

compiler. This object file format is the same one that is used 
by Unix systems. The file has five sections: a header, the 
program text, the program data, relocation information, a 
symbol table, and a string table (in that order). The text 
segment contains the actual rhachine code for the program, 
while the data segment contails initialized variables. A 
segment for uninitialized variables, called the bss segment, is 
set up at the time the program is run. 

Format using the C structure definitions are shown on the next 
page. 
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I* Header prepended to each object file. 
*/ 


long 

a ^magic; 

long 

a text; 

long 

a ^data; 

long 

a ^bss; 

long 

a ^syms; 

long 

a gentry; 

long 

a ^trsize; 

long 

a_drsize; 


]* Format ofa relocation datum 
♦/ 

typedef struct { 

long r_address; 

8/ 

unsigned long r_info; 

*/ 

} relocation__info; 


/* magic number 0x0107 */ 

/* size of text segment */ 

I* size of initialized data *l 

!* size of unitialized data */ 

/* size of sjrmbol table */ 

/* entry point */ 

/* size of text relocation *t 

I* size of data relocation *! 


/* address which is relocated ♦/ 

I* r ^symbolnum, r pcrel, r length, 

t* r extern *! 


/* Macros to access the r 
*/ 

#defme 

#deline 

#define 

#deflne 


.info field 

r ^symbolnum(x) 

r pcreUx) 

r__extem(x) 


((x>>8)&0xfEEEEfL) 
((x>>7)&0xlL) 
((x> >5) & 0x3L) 
((x> >4) & OxlL) 


If r__extem is zero, then r_symbolnum is actually the N TYPE (see 
below) for the relocation rather than an index into the symbol ta5le. 


1* Format of a symbol table entry. 

/* 

typedef struct { 

char *n name; 

!* string table index 

*/ 

char 

n__type; 
n pother; 

!* type flag, i.e. N_TEXT etc 

*1 

char 

/* unused 

*1 

char 

n ^desc; 

/* currently not used 

*/ 

long 

n value; 

/* value of this symbol 

V 

}nlist; 

/* Simple values for n_ 

#defmeN UNDF 

-type 

0x0 

/* undefined 

*/ 

#defineN ABS 

0x2 

/♦ absolute 

*1 

#defmeN“TEXT 

0x4 

/* text 

*t 

#defineN DATA 

0x6 

/• data 

*1 

#defineN BSS 

0x8 

/* bss 

*1 

#defmeN COMM 

0x12 

!* common (internal to Id) 

*1 

#defineN_FN 

Oxlf 

t* nie name symbol 

*1 

#deHneN EXT 

01 

/* external bit, ORed in 

V 

#defmeN__N-YTPE 

Oxle 

!* mask for all the type bits 

*1 
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Object File 

Format Object files are composed of up to four sections: a header, 

the text and data segments, an optional symbol table, and 
optional relocation information. The header, the first 
component in the file, specifies the size and starting 
address of the other components in the object file whichar 
are listed below. 


/* header 
*1 

typedef struct { 
int 

c ^magic; 

magic number (0x601 A) 

*/ 

long 

c text; 

size of text segment 

*1 

long 

c ^data; 

/* size of initialized data 

*/ 

long 

c hss; 

/* size of uninitialized data 

*/ 

long 

c syms; 

/* sizeof symbol table 
/♦ entry point 

*/ 

long 

c gentry; 

•/ 

long 

c_res; 

reserved, always zero 

.*/ 

} header; 




I* Symbol table entry 
*1 

typedef struct { 

char name[8]; 

int type; 

long value; 

} symbol; 


/* values for symbol types 

*/ 


#define 

DEFINED 

0x8000 

/♦ The symbol is defined 

*/ 

#define 

*/ 

#define 

EQUATED 

0x4000 

/* The symbol is an equate 

*/ 

GLOBAL 

0x2000 

/♦ The symbol is global 

*/ 

#deflne 

*/ 

#define 

*1 

EQU_REG 

0x1000 

/♦ The symbol is a register 

*/ 

EXTERNAL 

0x0800 

/♦ The reference is external 

*/ 

#define 

DAT REL 

0x0400 

/♦ Data segment reference 

*/ 

#de&ie 

TEX~REL 

0x0200 

/* Test segment reference 

*/ 

#define 

BSS REL 

0x0100 

/* Bss segment reference 

V 


*1 

The above values may be ORed together to indicate symbol 
type. 

One word {16-bit) of relocation information exists for each 
word of text and data. The type of relocation is indicated in 
bits 0-2 of the word. If the relocation is an external 
reference, the remianing bits (15-3) form an index into the 
symbol jable, indicating the name of the external reference. 
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/♦ relocation word values (bits 0-2) 

*/ 

#denne NO RELOC 0 

#define DATA BASED 1 

#derine TEXT“BASED 2 

#define BSS lASED 3 

#define UNDEF_SYMBOL 4 

#define LONG REF 5 

#define PR_RELATIVE 6 

#define INSTRUC^TION 7 
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2.4 LIBRARIAN 

Introduction 


Random Library 


The Tekeiec librarian, ar, maintains a group of files combined 
into a single archive, its main purpose is to create object file 
libraries to be used by the linker. 

The librarian is compatible with the UNIX program ar (file 
archiver). It also provides the function of the UNIX utility 
ranlib, which creates a dictionary of symbols that the linker 
uses to speed the process of searching through libraries. 


The ar command includes an option (I) which converts an 
archive of object files into a random library. This enables the 
linker to search the archive more efficiently. 

The librarian performs this randomization by examining the 
entire library, collecting global function and variable names, 
and information about the object modules in which they are 
defined, and writing a special component into the library. This 
component, named __SYMDEF, is always the first component 
of the library. 

fiJways randomize a newly created library. Once randomized, 
the librarian automatically re-randomizes any library which is 
changed. 

If a library has a .SYMOEF and it is changed, the librarian 
automatically recreates the ^SYMDEF. 

The usage of ar is on the following page. 
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Usage 


The ar command uses the following syntax; 

ar <key> [v3[pos] <afile> <flle> [file...] 

The ar fields are: 

key One of the commands listed below. 

t List a table of contents of the archive.. 

r Replace (add) file to the archive. If the 
archive does not exist, it is created. If an 
archive component name matches <file>, it 
is replaced. Otherwise <fiie> is appended 
to the end of the archive In the order 
specified. 

ra Same as option r, except the replace/add 
begins after the component in the archive 
named in [pos]. The file pos is first located, 
then the replace command is executed. 

d Delete file from archive. 

X Extract copy of file from archive. 

w Write the file to the standard output. 

I Convert archive Into random library. Always 

randomize a newly created library. 

V The letter v (verbose) can be appended to 
any of the commands, causing the librarian to 
print information about the action performed. 

pos Used with option ra. Indicates where the file 
is to be archived, pos is the file that the new 
file should follow in the archive. 

afiie Archive file name. 

file One or more file names, used according to 

key. 
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ERROR MESSAGES 


Table 2.4-1 lists the librarian error messages and their 
meanings. Also refer to section 2.8 which describes the 
global error codes that can be returned by the librarian. 


ERROR MESSAGE 

MEANING 

Usage: ar... 

An invalid key was specified, or not object or library files 
were specified. 

File open error: name 

The file name was not found. Check to see that the file 
name and path are correct, and that the file actually 
exists. 

File read error: name 

Try a newly formatted disk. 

File write error: name 

Disk is full or there is a physical program with the disk. 
The librarian writes a temporary file, called AR..TMP to 
the disk. Make sure there is adequate space available 
on both the librarian disk and the disk on which the 
library exists. 

File create error: name 

Unable to create a new library. Make sure that the disk 
is not write*protected, and that the path for the output is 
correct. Could also indicate a disk problem. 

Temporary file open error 

Unable to create the temporary file. There is either a 
problem witht he disk or the disk from which the librarian 
is being run is full. Make sure there is adeq'uate space 
available on both the librarian disk and the disk on 
which the library exists. 

File format error: name 

File given is not a library file. 

Memory allocation error 

Memory is exhausted. Remove RAM disk or cache. 

Malformed archive (OxXXX) 

The library file is internally corrupt. Create or copy a 
new file. The hex number given is the address where 
the librarian expected to find the beginning of a 
component file, but did not. 


Table 2.4-1: Librarian Error Messages 
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2.5 DISASSEMBLER 


Description The Disassembler, called dis, prints the assembly language 

equivalent of an object code file. This allows you to check the 
compiler’s code generation for errors or determine if it can be 
improved. 

If the file contains symbol information, it is used where 
possible; otherwise, actual reference values are printed. 
Since references internal to an object file are resolved by the 
compiler, there will be instances where no name is associated 
with a reference. In these instances, the Disassembler makes 
an educated guess as to the name of a reference, and prints 
it , rather than a value. All numeric values are printed in hex. 

The output of the Disassembler is not directly compatible with 
the in-line assembly of the compiler, because the compiler 
inserts extra characters that are not part of the assembler 
syntax. This additional information can be removed using the 
vi editor. 

The Disassembler uses Motorola mnemonics to print the 
assembly language equivalent of an object file. The 
disassembler prints labels as they would appear in an 
assembly language program by examining the symbol table 
and the relocation information. 

Usage The disassembler command uses the following syntax: 

dis [-n] [-r] [-a] [-1] ofile [ofiie . . . ] 

-n Suppress reference names and 

addresses. Print actual reference values. 
Default is for symbol names to be printed. 

-r Relative branches. Normally branch 

instructions, which specify addresses 
relative to the program counter, are 
converted to absolute addresses. This 
option suppresses the conversion. 
Default is the absolute address of the 
destination of the branch. 

-a Assembly format. Print as an assembly 
file, suitable for compiling. Often, slight 
modifications will be necessary before it 
will compile correctly. 
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-I Instruction print. The hex value of each 

instruction is printed before the instruction 
is disassembled. 

ofiie An object or executable file 


Disassembler 

Errors Table 2.5-1 lists the Disassembler error messages and their 

meanings. Also refer to section 2.8 which describes the 
global error codes that can be returned by the disassembler. 


ERROR MESSAGE 

MEANING 

Usage : dis ... 

An invalid option was specified or no object or 
program files were given. 

File open error: name 

The input file name was not found. Check to see 
that the file name and the path name are correct, 
and that the file exists. 

Memory full while 
processing 

Memory exhausted. Remove RAM disk or cache. 

File format error: name 

The file name is not an object or program file, or it is 
corrupt. - 


Table 2.5-1 : Disassembler Error Messages 
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2.6 EGREP 

Description 


Usage 

egrep.ttp [-C] [-L] [-V] [-N] [-S] pattern [files] 


-c 

Matching line count. 

This option prints the number of lines that 
matched the pattern. 

-L 

File listing. 

This option prints the file names 
containing matching lines. 

-V 

Print ail non-matching lines. 

This option prints the lines that do not 
match the pattern. 

•N 

Print line number. 

This option prints the line number of the 
matching line. 

-S 

Silent option. 

This option prints only error messages. 

[files] 



Egrep searches files for patterns that the user specifies. The 
patterns are in the form of regular expressions. Normally, 
each line that matches the user-defined pattern is copied to 
the standard output. Egrep patterns are extended regular 
expressions using a fast deterministic algorithm that 
sometimes needs exponential space. Lines are limited to 
1024 characters; longer lines are truncated. 

Egrep prints the file name If there is more than one input file. 


Egrep uses the following syntax: 
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Pattern 


Egrep accepts extended regular expressions. A regular 
expression specifies a set of strings of characters. A member 
of this set of strings is said to be matched by the regular 
expression. 

Care should be taken when using the characters $ * [ " | { ) 
and \ in the expression, as they may also be meaningful to the 
shell. It is safest to enclose the entire expression arguments 
in single quotes (’)• In the following description, the term 
character excludes newline: 

• \ (back slash) followed by a single character (other than 
newline) matches that character 

• * (caret)matches the beginning of a line 

• . (period) matches any character 

• Any other character matches that character 

• A string enclosed in brackets [ ] matches any single 
character from the string. Ranges of ASCII character 
codes can be abbreviated, for example, a-zO-9. A 
right bracket (]) can occur only as the first character of 
the string. A literal - must be placed where it cannot 
be mistaken as a range indicator. 

• A regular expression followed by an asterisk (*) matches 
a sequence of zero or more matches of the regular 
expression. 

A regular expression followed by plus {■*■) matches a 
sequence of one or more matches of the regular 
expression. 

A regular expression followed by a question mark (?) 
matches a sequence of zero or one matches of the 
regular expression. 

• Two regular expressions concatenated match a match of 
the first followed by a match of the second. 

• Two regular expressions separated by | or newline 
match either a match for the first or a match for the 
second. 

• A regular expression enclosed in parentheses matches 
a match for the regular expression. The order of 
precedence of operators at the same parenthesis level 
is as follows: [ ] then * + ?, then concatenation, then | 
and newline. 
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Examples If a file named test1 contains the line: 

The lazy dog jumped over the the cow 
To search for the word dog in the file, use egrep as follows: 
egrep ’dog’ testi 

To list all functions in a file, use egrep as follows: 

egrep ’‘([a-zA-2]|[__l) (a-zA-Z0-9]|[__]n r\(’ test2.c 

If test2.c is the following program: 

main() 

^ int i; 
foo(); 

foo() 

int i; 
main(); 

Egrep would print: 

main() 

foo() 
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Egrep Errors Table 2.6-1 lists egrep error messages and their meanings. 

Also refer to section 2.8 for a description of global error codes 
which can be returned by egrep. 


ERROR MESSAGE 

MEANING 

Usage : egrep.ttp... 

No pattern or files were given. 

Unable to open: name 

Egrep cannot open the file name. 

Unknown flag: flag 

Flag is not used by egrep. 

invalid regular expression 

Something is wrong with the regular expression. 

Unmatched ( 

A right parenthesis has been omitted from the 
expression. 

Unmatched ) 

A left parenthesis has been omitted from the 
expression. 

Premature end of regular 
expression 

The expression finished before it should have. 

Nesting too deep 

The nesting of parentheses was too great. 

Regular expression too big 

The expression was too big for egrep to compute. 

Memory Exhausted 

Egrep ran out of memory. 


Table 2.6-1 : Egrep Error Messages 
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2.7 SYMBOL NAMER 


Introduction Object files and application files can contain symbolic 

information in their symbol tables. This symbolic information 
can be printed using the Symbol Namer utility. 

Each symbol is preceded by Its value (In hexadecimal) and 
one of the following letters: 

• A Absolute 

• B Bss segment 

• C Common symbol 

• D Data segment 

• T Text segment 

• U Undefined symbol 

If the letter is lower case, the symbol is local. If upper case, 
the symbol is global. 


Usage 


The Symbol Namer syntax is: 
nm[fiie] 

file An executable file which has been 

linked so that it still has its symbol 
table. 


Error Messages Table 2.7-1 lists the Symbol Namer error messages and 

their meanings. 


ERROR MESSAGE 

MEANING 

Usage: nn... 

An invalid option was specified or no object or 
application file was specified. 

File open error: 

The input file was not found. Make sure that the file 
name and path name are correct, and that the file 
actually exists. 

File format error: name 

The file is not a valid object or application file or 
program file, or is corrupt. 

No name list 

The file has no symbol table. 


Table 2.7-1 : Symbol Namer Error Messages 
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2.8 GLOBAL ERROR CODES 


Description This table below lists the global error codes which may be 

returned when you are using C programs, such as the 
compiler, make, librarian, disassembler, or egrep. Additional 
error codes are listed in the appropriate section for each 
program. 


ERROR 

CODE 

MEANING 

0 

Successful (no error) 

-100 

No command given 

-101 

Error creating task 

-102 

Unable to get key 

-103 

Out of memory 

-104 

Invalid command line token 

-105 

Invalid priority 

-106 

No match on file name expression 

-107 

openvt error 

-108 

Ambiguous redirection 

-109 

Unable to open redirection 


Table 2.8-1: Global Error Codes 
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2.9 BASIC/SITREX/TEXT FILE CONVERSION 


Introduction 


General 

Guidelines 


The Chameleon 32 BASIC/SITREX/TEXT File Conversion utility 
provides the following file conversion capability: 

.• Converts a Chameleon BASIC (FRAMEM or SIMP/L) or 
SITREX program file to a text file 

• Converts a text file to a Chameleon BASIC/SITREX file 

This gives you the ability to write and edit your BASIC/SITREX 
programs using the C vi Editor, or a text editor on a PC or 
other computer. The text file can then be converted to a 
BASIC or SITREX program file and run on the Chameleon 32. 

The Chameleon 32 BASIC/SITREX/TEXT File Conversion utility 
requires that you have the optional C Package installed on 
your Chameleon 32. It includes the following programs: 

• totext Converts a Chameleon BASIC or SITREX file 

to a text file 

• tobas Converts a text file to a Chameleon BASIC or 

SITREX file 


General guidelines for using the conversion utility are listed 
below. Steps for performing a specific type of file conversion 
begin on page 2.9-3. 

1. Verify that the two conversion programs are in the \BIN 
directory of the Chameleon 32 hard disk drive. They are 
automatically copied to the correct directory when the 
system software is installed. 

Your environment (setenv) should contain a search path 
to the \BIN directory so that the conversion programs can 
be executed from any directory of the hard disk. 

2. If you are using vi or another text editor to write your 
BASIC or SITREX programs, be sure that your text files 
conform to the necessary syntax rules before you 
convert them. In the Chameleon 32 Simulation Manual, 
BASIC is described In Chapter 3 and SITREX is 
described In Chapter 8. 

3. BASIC and SITREX files have unique 2-character 
filename extensions and must be located in specific 
directories In order to be used. Figure 2.9.1 on the next 
page lists the extensions and directories for each file 
type. 
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FILE TYPE 

DIRECTORY 

FILE EXTENSION 

SITREX 

\TEKELEC\SIMULATE\SITREX 

.BA 

FRAMEM SDLC/HDLC 

\TEKELEOSIMULATE\FBOP 

.CB 

SIMP/L SDLC 

\TEKELEC\SIMULATE'SSDLC 

.DB 

SIMP/L HDLC 

\TEKELEC'SIMULATE\SHDLC 

.EB 

SIMP/L V.120 

\TEKELEC\SIMULATE\V1 20 

.GB 

BISYNC 

\TEKELEC'SIMULATE\BISYNC 

.HB 

ASYNC 

\TEKELEC\SIMULATE\ASYNC 

.IB 

FRAMEM OMI 

\TEKELEC\SIMULATE\FDMI 

.JB 

FRAMEM LAPD 

\TEKELEC\SIMULATE\FLAPD 

.LB 

SIMP/L LAPD 

SIMP/L MLAPD 

\TEKELEC\SIMULATE\SLAPD 

.MB 


Figure 2.9.1: Simulation Directories and File Extensions 


3. When executing the conversion programs, you can 
specify path names so that the BASIC/SITREX files do 
not have to be copied to a specific directory before 
converting. However, the amount of typing you do will 
be minimized if you change to the directory that contains 
the files you want to convert. 

4. Converted files are copied to the same directory 
containing the BASIC/SITREX file you are converting. 

5. Text files can be exchanged between the Chameleon 32 
and other computers using the following methods: 

• Files on 3 1/2” MS-DOS floppy diskette can be 
accessed directly from the Chameleon 32 floppy 
disk drive or copied to the hard disk. 

• Files stored on other media can be transferred with 
the Chameleon 32 Kermit File Transfer utility. In 
order to use Kermit, the other computer must have 
a Kermit-compatible file transfer program. 

Text files should be transferred using the Kermit 
text mode option. 

Refer to the Chameleon 32 User’s Guide, Chapter 
10 for more information about Kermit file transfer. 
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Converting BASIC/SITREX Files to Text Files 


The totext program converts a Chameleon 32 BASIC or 
SITREX file to a text file so that it can be edited with the C vi 
Editor or a text editor on another computer. 

To convert BASIC/SITREX files to text files, do the following: 

1 . Copy the files you want to convert to the directory a:\usr. 

BASIC and SITREX files are located in specific 
directories of the hard disk and have unique 2-character 
file extensions. This information is listed in Figure 2.9.1 
on page 2.9-2. 

2. Access the C Shell prompt and change to the directory 
a.-lusr. 

3. Execute the totext program using the following syntax 

totext filei.ext fileZ.ext 

filei.ext filel is the BASIC/SITREX program filename 
of 1 - 8 characters. 

ext is the 2-character file extension specific to 
each type of file as listed in the Figure 2.9.1 
on page 2.9-2. 

file2.ext You can convert more than one file at a time, 
by delimiting each filename with a space. 

You can also use wildcards to convert more 
than one file at a time. 

4. When converted, the text file will be located in the a:\usr 
directory. The new file will have the same filename as 
the BASIC/SITREX file, with the file extension .ED. 

You can edit the text file with the C vi Editor, or use the 
Kermit File Transfer utility to transfer the file to another 
computer. 

5. After editing the text file, you must convert it back to a 
BASIC or SITREX file and copy it to the appropriate 
directory before you can use the program on the 
Chameleon 32. 
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Converting Text Files to BASIC/SITREX Files 

The tobas program convert a text file to a Chameleon 32 
BASIC or SITREX file. After converting a text file to a 
BASIC/SITREX file, it must be copied to the appropriate hard 
disk directory before it can be used. This information is listed 
in Figure 2.9.1 on page 2.9-2. To convert a text file to a 
BASIC/SITREX file, do the following: 

1. Access the C Shell prompt (I). 

2. Copy the text files to the directory aAusr. 

If they are located on another device, use the 
Chameleon 32 Kermit File Transfer Utility to transfer them 
from the other device to the Chameleon 32 hard disk 
drive. The text file must be transferred using the Kermit 
text mode option. 

3. Execute the tobas program using the following syntax: 

tobas -type filei.ext -type fiie2.ext 

-type -type is the 2-character file extension for the 
type of BASIC/SITREX file being created. 

For example, a FRAMEM HDLC file must have 
the extension .cb, therefore if you were 
converting a text file to FRAMEM HDLC, the 
type would be -cb. The type must be one of 
the following in lower case letters: 


IF CONVERTING TO: 

USE THE TYPE: 

SITREX 

-ba 

FRAMEM SDLC/HDLC 

-cb 

SIMP/L SDLC 

-db 

SIMP/L HDLC 

-eb 

SIMP/L V.120 

-gb 

BISYNC 

-hb 

ASYNC 

•ib 

FFIAMEM DMI 

-jb 

FRAMEM LAPD 

-lb 

SIMP/L LAPD 

SIMP/L MLAPD 

-mb 
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fiiei.ext filel is any valid MS-DOS filename of 1 - 8 
characters. 

ext is a 1-3 character file extension. 

file2.ext You can convert more than one file at a time, 
by delimiting each filename with a space. 

You can also use wildcards to convert more 
than one file at a time. 

4. When converted, the file will be located in the same 
directory as the text file. The new file will have the same 
filename as the text file, with the file extension specified 
in the type parameter. 

Before you can run the converted BASIC/SITREX file it 
must be copied to the appropriate directory and given 
the correct file extension as indicated in Figure 2.9.1 on 
page 2.9-2. 
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3.1 MAKE UTILITY 

Introduction Programmers often divide large programs into smaller pieces. 

These smaller units are easier to work with on an individual 
basis, but tracking the relationships and dependencies among 
the pieces becomes a time-consuming task. As you modify 
your program, it is difficult to remember which files depend on 
which others, which files have been modified, and the exact 
sequence of operations needed to make or test a new version 
of a program. 

make automates a number of program development activities 
so that you can maintain up-to-date versions of your 
programs with a minimum of effort. 

• Find the name of a specified target file{s) 

• Ensure that the files that the target depends on 
(dependencies) exist and are up-to-date 

• Update or create the target to incorporate modifications 
that have been made to the dependencies since the 
target was last modified 

Makefile To use make, you create a description file, referred to as a 

makefile, that identifies the target files, the dependencies of 
the targets, and commands. The information in the makefile 
enables make to identify the operations necessary to update 
and compile your program after you make modifications. 

Built-In Rules In addition to the Information in the makefile, make maintains 

a table of built-in rules in a special makefile called 
SUFFIXES. It uses the information in SUFFIXES to determine 
which file name suffixes are interesting, and how to transform 
files with specific suffixes into files with other suffixes. 

For example, a rule in the SUFFIXES table could specify that 
files with a .c suffix (C source files) are to be transformed into 
.o (object files). This rule causes C source code files to be 
compiled. 

You can add or modify suffixes and rules in the SUFFIXES 
table, thus enabling you to define global rules that make will 
apply to any makefile. Additionally, you can inhibit the use of 
built-in rules in the SUFFIXES table by entering the make 
command -r option, described later in this section. 

Macro Feature make includes a macro substitution facility that enables you to 

perform string substitution in dependency lines and command 
strings. 
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MAKE COMMAND 


Syntax 


The make command executes commands in a makefile, 
causing specified target files to be updated or created to 
reflect changes made to files they depend on. 

The make command executes the file with the default name 
MAKEFILE, unless a different name is specified. 

The syntax of the make command is shown below. Items 
enclosed in square brackets [ ] are optional items. 

make [opt] target] [macro = value] [Fname . . .] 

The make command fields are described below. 

opt The following options are available: 

-I Ignore error codes returned by invoked programs. 
Alternately, you can ignore error codes, using two 
other methods: 

• Enter .IGNORE as a false target in the 
makefile 

• Press TAB - (tab followed by a hypen) 
preceding a command in the makefile 

-N No execute mode. Print commands, but do not 
execute them. 

•R Do not use Make Utility built-in rules specified in 
SUFFIXES. Alternately, you can inhibit the use of 
the SUFFIXES table by entering .SUFFIXES, without 
a dependency list, as a false target name in the 
makefile. 

-S Silent mode. Do not print command lines before 
executing. Alternately, you can specify silent 
mode, using two other methods: 

• Enter .SILENT as a false target in the 
makefile 

• Enter @ as the first character of a command 
in the makefile 

-P Print ail macros and targets 
-Q Question up-to-dateness of a target 
-X Print a list of all targets in the makefile 
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MAKEFILE 

STRUCTURE 


Entries 


target The names of one or more target file names 

separated by a blank space. If target files are 
not specified in the make command, the 
target{s) specified in the first line of the 
makefile are updated/created. 

macro -value Define a macro (see page3.1-6) 

-Fname The name of the makefile to use. In the 

absence of this option, make looks for the 
default name of MAKEFILE. More than one 
-fmakefile parameter can occur in a make 
ommand. 


To use the make command, you create a makefile that 
specifies the target files and the files that depend on them. A 
makefile contains the following information: 

• Entries ( targets + dependencies + commands) 

• Comments 

• Macros 

The entry is the most important part of a makefile. It consists 
of the target file names, their dependencies, and command 
lines. 

There are two types of entries: 

• Dependency lines 

• Command lines 

The general form of an entry is described below. Note that 
Items in square brackets [ ] are optional items; items in 
parentheses are mandatory. An ellipsis (...) indicates that 
more than one like item can be entered. 

A dependency line defines the target files and their 
dependencies (the files that the target depends on). 
Optionally, a dependency line can contain one or more 
commands. The form of a dependency line is: 

target...^:] [dependent...] [, -command...] 

A command line contains a progra name followed by program 
parameters. Command lines must begin with a TAB. The 
form of a command line is: 

(tab)[command...] 
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The items in a makefile entry are described below. 

target The target is the name of one or more target files. 

These are the files that you want updated or 
created. Target names are strings of letters, digits, 
periods, and slashes. Multiple target names are 
separted by blank spaces. Shell metacharacters * 
and ? are expanded. 

dependent The dependent is the name of one or more 
files that the target files depend on. Dependent 
names are strings of letters, digits, periods, and 
slashes. Multiple dependent names are 
separated by blank spaces. Shell 
metacharacters * and ? are expanded. 

: You can use a single colon (:) or double colon (::) 

to separate the targets from the dependencies. A 
target name can appear on more than one 
dependecy line, but all lines that it appears on must 
be of the same (single or double colon) type. 

If a target appears on more than one dependency 
line, and a single colon is used, only one of the 
dependency lines can have a command sequence 
associated with it. if the target requires updating, 
and a command sequence is specified, it is 
executed. 

If a target appears on more than one dependency 
line, and a double colon is used, each dependency 
line can have a command sequence associated 
with it. If the target requires updating, the 
associated commands are executed, including 
built-in rules. The double-coion form is valuable 
for updating archive-type files. 

command A command is a program name followed by 
optional program parameters (any string of 
characters, excluding a # or carriage return). 

Commands can appear on a dependency line or 
on the line immediately following a dependency 
line. If a command appears on the dependency 
line, it is preceded by a semicolon. If a command 
appears on the line following a dependency line, 
the command line must begin with a tab. 
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Command lines are executed one at a time, each 
by its own shell. This is important to remember 
when using commands that have meaning only 
within a single Shell process; the results are 
forgotten before the next line is executed. These 
types of commands include cd and Shell control 
commands. 

A line is printed when it is executed unless the 
make command -s option is used or .SILENT is 
entered as a false target name in the makefile. 

Commands returning nonzero status cause the 
make command to terminate unless the make 
command -I option is used or .IGNORE is entered 
as a false target name in the makefile. 

Some commands return nonzero status 
inappropriately. Use the make command -i option 
or begin the particular command with <TAB> 
< HYPHEN > in the makefile. 

Make remembers embedded newlines and tabs in 
Shell command sequences. If you write a for loop 
in the makefile with tabs, make retains the tabs 
and backslashes when the commands are 
displayed. Output can be piped to the Shell and is 
readable. 

Command lines can appear on a dependency line or on the 
line immediately following a dependency line. If a command 
appears on the dependency line, it is preceded by a 
semicolon. If a command appears on the line following the 
dependency line, thecommand must begin with a tab. 

A line is printed when it is executed unless the -S options is 
used or .SILENT is entered as a false target name in the 
makefile. 

Commands returning non-zero status cause make to 
terminate, unless the -I option is used or .GNORE is entered 
as a false target name in the makefile. Some commands 
return non-zero status inappropriately. . For these cases, use 
the -I option, or begin the particular command with (tab) 
(hyphen) in the makefile. 
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Entry logic 


Comments 


Macro Definition 


The order of your entries in a makefile is significant Lower 
level dependencies must be defined before higher level 
dependencies. For example, If target A depends on B, and 
target B depends on C, the entries must appear in the 
following order in the makefile: 

B:C 

A:B 

This logic causes make to update B based on C, before it 
updates A from B. In order for make to update your files 
correctly, you must use this logic when creating your 
makefiles. 


The pound sign {#) indicates a comment. All characters, from 
a pound sign to the end of the line, are ignored. Blank lines 
and lines beginning with # are ignored totally. Comments can 
appear on dependency lines or command lines. 

Make also provides a simple macro substitution facility for 
substituting strings in dependency lines and commands. 

A macro line contains an equal sign { = ) which is not 
preceded by a colon or a tab. The macro name is the string 
to the left of the equal sign (trailing blank and tabs are 
stripped). The macro is assigned the string of characters to 
the right of the equal sign (leading blanks and tabs stripped). 

For example, to define a macro named PROGRAM as the 
three object files, l.o, 2.o and 3.0, you enter: 

PROGRAM = 1.0 2.0 3.0 

You can assign a null string as a macro value by leaving the 
right of the equal sign blank. For example, to assign a null 
value to the macro named ZIP, enter 

ZIP = 

You can also define macros in the make command itself. 

A macro is invoked using a dollar sign ($) as shown below: 

$<macro name) or ${macro name} 

If the macro name is a single character, the parentheses or 
braces are optional. Macro names exceeding one character 
in length, must be enclosed in parentheses ( ) or braces { }, 
as shown. 
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Implicit Macros 


Dynamic 

Dependency 


For example, to invoke a macro named Y, a single-character 
name, enter either: 

$Y or $(Y) or ${Y} 

To invoke a macro named PROGRAM, enter either: 

$(PROGRAM) or ${PROGRAM} 

There is also a facility to perform translations when a macro is 
referenced and evaluated. The general syntax for a macro 
reference is: 

${macro : stringl = string2) 

This causes each occurrence of stringl to be substituted with 
string2 in the macro being evaluated, where macro is the 
name of the macro being evaluated. All environment 
variables which are defined as make is executed, become 
macro definitions in make. 


If a file is generated using one of the built-in transformation 
rules, the following macros can be used: 

• $* Name of the file to be made (excluding the suffix) 

• $@ Full name of the file to be made 

• $< List of the dependencies 

• $? List of dependencies that are out of date 


To use these implicit macros, there is a dynamic dependency 
parameter referenced by the notation: 

$$@ 

It has meaning only when it appears on a dependency line. 
The $$@ refers to the item(s) to the left of the colon, which is 
referenced by the $@ implicit macro. 

The following is an example using implicit macros and the 
dynamic dependency parameter. 

PR06s= si s2 S 3 s 4 Defines macro PROGS as files s1 - s4. 

$(PR 06 S) ; 8.C Invokes the PROGS macro, defining the 

target file names as s1, s2, s3 and s4. 
Defines their dependencies as C source 
files (.c) with the same filenames; s1.c, 
s2.c, s3.c, and s4.c. 
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SUFFIXES TABLE 


Transformation 

Rules 


There is also a second form of the dynamic dependency 
parameter which refers to the file part of $@. This form is 
referenced using the notation $$(@F). 


As mentioned previously, make maintains a table of suffixes 
and built-in transformation rules in a suffixes table. You can 
change the table with the .SUFFIXES directive. For example: 

# Add the suffixes .o and .c to the suffixes table 
.SUFFIXES : .o .c 

When attempting to determine a transformation for a file which 
has no explicit target mentioned in the makefile, make uses 
the suffixes table. Make looks for a file with the desired suffix, 
and uses the associated transformation rule to create or 
update the target file. 

Table 7-1 lists the default suffixes in the SUFFIXES file. 


SUFFIX 

FILE TYPE 

.0 

Object file 

.c 

C source file 

.r 

Ratfor source file 

.s 

Assembler source file 

•y 

Yacc-C source grammar 

•p 

Pascal source 

.1 

Lex source grammar 

.h 

Include file 


Table 7-T. Default Suffix List 


A transformation rule name is the concatenation of the two 
suffixes. For example, the name of the rule that tranforms .c 
files to .0 files is .c.o. For example: 

# Compile (with CC) a .c file to produce a .o file 
.c.o 

CC -c $*.c 


Tekelec 


3.1-8 


Version 2.2 






Chameleon 32 C Manual 


Ch.3.1: Make Utility 


A transformation rule is used only if the user’s makefile does 
not contain an explicit command sequence for these suffixes. 

The order of the SUFFIXES list is significant. Make scans the 
list from left to right, and uses the first name that has both a 
file and a rule associated with it. To append new names to 
the suffix list, enter SUFFIXES as a special target in your own 
makefile, listing the new suffixes as dependencies. The 
dependencies will be added to the suffix list. 

For example, to transform a source file into an object (.o) file, 
make calls up the appropriate compiler. There are also 
transformation rules to create library (.a) files from source 
files. 

To delete the built-in suffix table, enter .SUFFIXES as a 
target, without listing any dependents in the makefile. It is 
necessary to do this to clear the current list, if changes in the 
order of the suffixes is desired. 
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EXAMPLES 


Some example makefiles are described below. 

Example 1: For this example, the SUFFIXES files contains a 
built-in rule that enables make to compile three source files, 
x.s, y.s and z.s to generate the needed object files x.o, y.o 
and Z.O. (tab) indicates that you enter a tab character. 


#Exaap1e 1 

# 

prog: x.o y.o z.o 


(tab) cc x.o y.o z.o -o prog 


x.o y.o: defs 


States that the target file prog 
depends on three object files: x.o, 
y.o, and z.o. 

Describes how to load the three 
object files to create prog. Note 
that command line begins with 
TAB. 

The target files x.o and y.o depend 
on the header file defs. 


Example 2: This example illustrates the use of macros. 


OBJECTS > x.o y.o z.o 

LIBES -la 
prog: S(OBJECTS) 

(tab) cc $(OBJECTS) S( LIBES) -o prog 


Defines the macro OBJECTS to be 
the three object files x.o, y.o and 

Z.O. 

Defines the macro LIBES as -Im. 

Defines the dependencies of the 
prog target file as x.o, y.o and z.o 
by invoking the macro OBJECTS. 

Builds the target prog by loading 
the three object files with the Im 
library. 
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4.1 MACHINE DEPENDENCIES 


Data Elements 


The C compiler supports all of the standard scalar types of 
the C language; char, int, short, long, unsigned, float, and 
double, as well as pointers to all types. Also unsigned char 
and unsigned long are supported. The amount of space 
allocated for each data type (in terms of 8-bit bytes) is as 
follows: 


char: 1 

unsigned; 2 

short: 2 

int: 2 

long: 4 


unsigned char; 1 

unsigned long: 4 

float: 4 

double: 8 

“anything: 4 


Floating point types are stored in IEEE standard format. 

The maximum size of an identifier or string constant is 255 
bytes. 

Space for variables of type char and short are allocated on 
the next available byte boundary in memory if the variable is 
within a struct or union or is of storage class auto, or on 
the next available word boundary if the variable is extern or 
static. Space for all other variables, including those of any 
other storage class as well as arrays, struct’s and union’s, is 
always allocated on the next available word boundary, 
regardless of storage class. Bit fields within struct’s are 
allocated in unsigned units, starting from the least significant 
bit. 


External Names Identifiers (names of variables and functions) may contain up 

to 255 characters each. Only the first ten characters are used 
to distinguish one identifier from another, however. As per the 
standard for the C language, both upper and lower case 
letters are allowed in identifiers, and are distinct from each 
other. In other words, the names myvar and MyVar are 
different. The underscore character ( ) is also legitimate 
within identifiers, as are digits. The only" restriction is that an 
identifier may not begin with a digit. It should be noted that 
various internal functions, such as floating point routines and 
support for long integers, have names beginning with an 
underscore. Programmers should therefore avoid extern 
identifiers beginning with an underscore if possible. 
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Include File 
Processing 


Floating Point 


Register Variable 
Support 


The #include feature of the standard C preprocessor allows 
file names to be given within either double quotes or angle 
brackets. Angle brackets will cause the compiler to look in 
“include”. Double quotes cause the compiler to look first in 
the directory containing the ".c" file being compiled and then 
to look inthe predefined places. 

Include files may be nested to a depth of 6 levels, - including 
the main module level. An attempt to nest beyond this 
maximum (such as would be the case if an include file 
inadvertently # included itself) results in an error message. 


All floating point operations in Tekelec C can be carried out in 
either single (32 bit) or double (64 bit) modes. The single 
precision mode is the default and is about three times faster 
than double mode. 


Each function in a C program can expect up to three registers 
available for register storage class variables. One data 
registers is available for integral types (char, short, int, long, 
and unsigned), and two address registers are available for 
pointer variables. Judicious use of register variables can 
substantially increase execution speed and decrease code 
size. 


Tekelec 


4.1-2 


Version 2.2 



Chameleon 32 C Manual 


Ch.4.2: Compiler Processing 


4.2 COMPILER PROCESSING 


Error Processing Error messages generated during compilation are reported to 

the screen, accompanied by the line of source code 
containing the error. Error messages are of the form 

"f i 1 e-naine". line line-number: error message text 

To simplify correction of errors in a program, error messages 
may be redirected to a file (see Shell: I/O redirection). This 
file may be used while editing the source to correct mistakes. 


Code Generation The C compiler, including preprocessor, syntax check, and 

code generation, is one-pass. In other words, all work which 
needs to be done by the compiler is finished after looking at 
the contents of the source file once. The compilation process 
is thus quite fast. 

Linkable object code is generated directly by the compiler; 
there is no assembly post-pass. C performs many processor 
specific "strength reduction" optimizations, such as using 
MC68000 "quick" instructions, replacing multiplies and divides 
by powers of two with shifts, and avoiding intermediate register 
loads when possible. Simple statements, such as increments 
and assignment operations involving constants, frequently 
generate only one machine instruction. 

For example, the statement 

i+ +; 

compiles into a single instruction to increment the variable i. 
The statement 

i = 50; 

will compile to a single MOVE instruction. 

Certain expressions involving constants will be evaluated at 
compile time. 

Therefore, the statement 

i + = 5 * ARRAYSIZ; 

will generate one ADD instruction, assuming ARRAYSIZE is a 
constant which was #def i ned. 
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4.3 RUN-TIME PROGRAM STRUCTURE 

Each program is executed under MTOS-UX as a task. As a 
task is initiated, it creates a “virtual terminal" on the 
Chameleon 32 screen through which standard (terminal) 
input/output is done. Calls to C memory allocation routines 
(malloc and calloc) allocate memory from an MTOS-UX 
memory pool which is created when the Chameleon 32 is 
booted. All tasks allocate and deallocate from this pool (pid is 
“POOL”). As a task terminates, it is killed and all memory 
allocated by the program (throughmal loc and calloc) will 
be returned to the pool. Programs may call MTOS-UX 
memory pool management routines directly, but must assume 
responsibility for resource disposal. 

C stores all string constants with a terminating null byte, as 
per the standard for the C language. 


System Library All code for functions from the system library is included in 

each executable program by the linker. 


Program 

Entry/Exit 


Function Call 
Conventions 


When a program is linked after compilation, an object module 
containing startup code is automatically included by cc. The 
following declaration will allow program parameters: 

main (argc, argv) 
int argc; 

char *argv[]; 

where argc is the number of strings in the argv array. 
Argv[0] is always the program name. If you do not need 
program parameters, just declare main{) without any 
parameters and the linker will not include the code to handle 
them. 


Parameter expressions encountered in function calls are 
evaluated and then passed to the function on the stack. The 
parameters are pushed in the reverse of the order given in 
the parameter list. Reversal of the parameter list is necessary 
for functions with variable numbers of parameters. Such 
functions may access lists of parameters as follows: 
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max(n, p); 

/♦ Return max of list of into; n gives list length ♦/ 
int n, p, { 

int ♦pp, max = -32768; 
for {pp*&p. n. PP++, n— ) 
if (max < •pp) 
max = •pp, 
return max; 

} 

The above function niax() returns the maximum of an 
arbitrary number of integers. The number of integers is 
passed as the first parameter, followed by the list of values: 

m = max(5, i, j, k * 2, 87, f(abc)); 

Note that the pointer variable pp is incremented in the for 
loop of the above function. The pointer will move down 
through the stack towards higher memory locations retrieving 
each parameter in turn. Any functions which use this method 
of obtaining parameters are not necessarily portable to other 
implementations of C. 

Values are returned from functions in processor register DO. It 
is the responsibility of the calling environment to remove 
parameters from the stack after return from a function call. 
Each function must ensure that any registers used to hold 
register variable values are saved and then restored when the 
function terminates. 

Structs may be passed by value. 
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4.4 LIBRARY IMPLEMENTATION 

Line Separators Because of the heritage of the C language, the ASCII line 

feed character (numerically, 10 decimal) is usually considered 
to be the line separator character. 

In text files, a line feed separates lines, however, upon output 
to the screen, line feeds are automatically converted to 
carriage return/line feed pairs. 


Memory 

Allocation The memory allocation routines malloc() and canoc() 

are available to the C programmer. To avoid excessive 
fragmentation of the common memory pool, memory is 
allocated in 8 KB blocks, breaking up the blocks as necessary 
to satisfy the requests made from the C program. The 
f ree( ) routine will coalesce space which is returned and the 
allocation system will reuse deallocated space. 

Note that because pointers are 32 bits long, a C program can 
use as much memory as is available on the machine through 
dynamic allocation. 

IMPORTANT NOTE: you must make the declaration: 
extern char ♦mallocO; 

in your program before you use mall oc (the same is true for 
calloc). If you don’t do this the compiler will assume mall oc 
returns an int (which Is only 16 bits wide). 

Also note that malloc requires an unsigned int as its 
parameter. If more than 64 Kbytes of memory is needed, 
MTOS-UX memory allocation routines may be used (see 
malloc 0, alloc () ). 
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4.5 LANGUAGE EXTENSIONS 


ASSEMBLER 

Introduction The Tekelec C compiler allows the addition of assembly 

language code to a C program directly in-line with the C 
code. The C language has been extended to include the 
construct: 

asm { 

MCesOOO Assembler Instructions 

} ■ ■ ■ 

The code within the braces after the keyword asm is 
assembled and included in-line with code generated from 
surrounding C statements. 

The in-line assembler obviates the need for a separate 
assembler. General control structure, inpuVoutput, and 
complex data structures can be implemented in C, while 
certain low-level routines can be coded in assembly 
language within the same module. The problem of interfacing 
C functions to assembly language functions and vice-versa 
is eliminated, because calling sequences can be written in C 
for functions coded in assembler. Programs can first be 
developed in C to debug algorithms and to generate quickly a 
working prototype. Functions which comprise the most time 
consuming sections of the program (generally less than 10% 
of the code) can then be re-coded in assembly language. 
Because of the efficiency of the C code generator, such a 
hybrid approach yields execution speeds favorably 
comparable with pure assembly language code while retaining 
the ease of modification and maintenance of a pure high- 
level language approach. 

Use of assembly language decreases readability, exacerbates 
debugging headaches, and drastically reduces portability. 
Discretion must be used when considering functions for hand 
translation. There are some situations where speed is critical, 
most notably graphics. Such applications frequently involve 
system or machine dependencies anyway, so portability is not 
an issue. In such cases, the availability of in-line assembly 
language is a great benefit. 


Syntax The general syntax for in-line assembly language follows. 

{stuff} means stuff is repeated one or more times, 
(choicel I choiceZ 1 . . .) means one of the choices 

must appear, [stuff] means stuff is optional. 
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<asfn~statement> — > asm {{<asm“l ine>}} 

<asm-11ne> — > {<label>: |<op-code>C. (B|W|L|S)][<operand> 

[ , <operand>]]}[ ( ; <comment> 1 /•<cominent>*/ ) ] 

<operand> — > (0<n>|A<n>l(A<n>)+|-(A<n>) |<disp>{A<n>) | 

<disp> (A<n>.<ix>)|<constrxpr|[.W|L]|<disp.(PC,<ix>| 

#<const8xpr> | <regl i st> | CCR | SR | USP ) 

<d1sp> — > (<1deiitif ier>[{+|-)<constexpr>]|<constexpr>) 

<1x> — >(A<n>|D<n>)[.(y|L)3 
<n> — >(0|1|2|3|4|5|617) 

<reglist> — > (<reggroup>)/<reggroup> 

<reggroup> — > {A<n>|0<n>)[-A<n>|D<n>)] 

The syntax of the in-line assembler is almost identical to that 
described in the Motorola 68000 manual. Exceptions are 
noted below. 

In-line assembly may appear anywhere in your program; it is 
not necessary to place it inside a function. Please note that 
<1dent1fier> is the same as a C identifier, and 
<constexpr> is the same as the C constant expression. 
Opcodes are the same as in the Motorola literature and may 
be given in upper or lower case. The size modifiers B , W , L, 
and S can also be given in upper or lower case. The register 
names are defined only in uppercase. Expansion of 
^defined macros is performed within sections of assembly 
language, so the programmer is free to rename, instructions or 
registers. 

Each line of assembly language may consist of one or more 
instructions, optionally followed by a semicolon and comment 
text. Comments may also be given as C comments. Note that 
^defines can be used to create simple macros, using the 
multiple statement per line feature. Within macros, C style 
comments must be used instead of the normal semicolon- 
to-end-of-line assembly language comments. 

Expressions which give displacement values are restricted in 
that only one identifier may be Involved. A constant 
expression may be added to or subtracted from this identifier, 
in such expressions, the identifier must be placed first in the 
expression; in other words, the statement 

MOVE DO. x+2(A4) 
is legal, but the instruction 

MOVE DO, 2+x(A4) 
is not. 

The application of addressing modes to instructions is not 
completely orthogonal in the MC68000 instruction set. For 
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complete information on addressing modes and instruction 
forms, consult a Motorola databook. 


If no size specifier is given for an instruction which can 
operate on more than one size, the assembler defaults to 
word. If a size specifier is not applicable to a particular 
instruction, no specifier may be given. All labels given default 
to local code labels unless declared as something else 
previously. This means that all functions called, for example, 
must be declared or defined previously in C. 

Branches default to word-sized displacements. The code 
improver will change the word branches to short branches 
where possible. A short branch can be forced by using a . s, 
but no warning message will be given if the necessary 
displacement is too large for a short branch. 


External and static variables from the C environment are 
accessed using the name of the variable. Auto variables are 
accessed using the name of the variable as the displacement 
from the A6 register (the Address Register Indirect with 
Displacement mode). Register variables may also be 
accessed by name. The first four non-pointer register 
variables are placed in data registers; the first two pointer 
register variables are placed in address registers. Any excess 
register variables must be accessed relative to A6. The 
assembler will not report misuse of any variable names. 

Functions in the C program can be referred to by name. 
Arguments are passed to functions on the stack in reverse of 
the order they are written in C. Values are returned from 
functions in data register DO, or in global_f pregO if the value 
is double. 


Registers D0-D3 and AO and A1 may be used without saving 
them. Registers D4-D5, A2, and A3 are used for register 
variables, and are allocated in reverse numeric order. Each of 
these registers not used for a register variable within a 
function containing in-line assembly language must be saved 
by the assembly code if modified therein. Register A6 is used 
to access auto variables. 


This section is not for the novice user of the in-line assembly 
and discusses the use of a construct that is very dangerous. It 
is almost never needed and should be avoided if at all 
possible. 
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The normal functions in C start with a link instruction to make 
room for local variables and then end with a corresponding 
unlink instruction. These instructions can be avoided by 
making a label inside assembly to be called instead of the C 
function name. A rts instruction must also be placed at the 
end of the routine to avoid the unlink instruction. To indicate 
that this is an extern or static symbol it must be so declared 
before It is used as a label. This is done by declaring it as an 
extern or static function in C. Remember, by overriding the 
normal entry point a lot of nice things that C does about 
parameter passing and setting up local variables is lost. 


Assembly Language 
Example 

/• 

Function to do a block move from the first pointer to the. The routine moves 
one char at a time to allow odd addresses. 

•/ 

b1ock_move (source, dest, count) 

register char •source, ♦dest; /• uses address registers •/ 
register int count; /• placed in a data register •/ 

{ 

asm { 

subq #1, count ;because dbf counts to *1 

Ip : move.b (source)-*-, (dest)-*- 
dbf count. Ip 

} 

} 

/• 

An example of a macro to use in assembly language 

•/ 

^define INC(x) addq #1, x 
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C supports structure and union assignment and passing. If x 
and y are structures of type stype then the following 
statements are legal: 

X s y ; /• contents of y are copied to x •/ 

foo(x); /• X is passed by value to f oo( ) ♦/ 

struct stype bar(); /• function returning struct •! 


The definition of character constants has been extended in C 
to allow int and long size as well as char. The syntax is a 
single quote followed by 1, 2 or 4 characters and a closing 
single quote. The resultant type will be a char, int or long 
respectively. 


In general, name scoping within the C compiler is as per 
standard C. One exception to this standard is the treatment 
of identifiers of structure members. In Tekelec C, structure 
member names need not be unique across struct boundaries. 
Therefore it is valid for two different structures to contain 
members at different relative offsets with identical names. 

A restriction imposed by the one-pass nature of the Tek '’ec 
C compiler is that static functions must be declared before the 
first reference in a program. The declaration need not be the 
definition of the code of the function. A simple declaration 
such as 

static my-func( ) ; 
will do. 


A problem arises when two structures must refer to each 
other: the reference in the first structure causes an undefined 
type error because the second structure hasn’t been defined 
yet. This mutual referencing almost invariable arises with 
some kind of linked data structure. The Tekelec C compiler 
has been extended to allow pointer references to structs or 
unions that have not yet been defined. Note that this only 
works with pointers to structs or unions with a tag name 
(typedefs will not work). Additional errors will be generated 
later in the compile if the struct or union is never defined. 
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5.1 LIBRARY INDEX 


Introduction The functions described in this chapter are compatible with 

functions by the same names which are available to C 
programmers using the UNIX operating system. Most of these 
routines are available in all C implementation; even those on 
microcomputers without UNIX. Therefore, use of these 
functions simplifies the task of porting a C program to another 
computer. 


File I/O The system library contains routines for buffered and 

unbuffered inpuVoutput to disk files. Buffered routines, for the 
stream file interface, begin with the the letter f. The 
unbuffered routines are the low-level read() and write() 
routines. Both levels of I/O allow random access to disk files. 
Along with these routines you can use the BIOS routines for 
input/output. 

/ 

Stream I/O A stream file is a pointer to a FILE data structure declared in 

the head file STDIO.H. Each stream is associated with a 
regular file via a file descriptor returned by open or creat. 
Streams buffer data through the file descriptor so that single 
character I/O is efficient. To increase speed, you can change 
the default buffer size (512 bytes) using the setbuffer call. 
Streams provide a larger number of functions than the Basic 
I/O level. 

Three streams are open when a program start: 

• stdin Open for reading only, and is connected to 

the keyboard (file descriptor 0). 

• stdout Open for writing only, and is connected to the 

screen (file descriptor 1). 

• stderr Open for writing only, and is connected to the 

screen (file descriptor 1 ). 
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I/O Redirection 
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I/O redirection is a mechanism where stdin and stdout are 
changed from using the keyboard and screen, to using files, 
as follows: 

• stdin Changed by passing < INFILE on the 

command line. 

• stdout can be changed two ways: 

^ > OUTFILE opens and erases outfile 

y >> OUTFILE appends to an existing 
outfile 

You do not have to change the program for I/O redirection to 
work, although you must declare the parameters argc and argv 
for main(). 


All system devices are available to you through the C 
input/output system. For most device input/output, it is wise to 
use setbufO to prevent buffering on the stream connected to 
the device. 

When using the unbuffered input/output services, the only 
significant flag in the mode word is the blnaiy (O BINARY) 
flag. If this flag is set, there will be no special tr^ment for 
line separator characters. Note that you cannot creat() a 
device. 

You can use BIOS routines to manipulate devices, but these 
routines require the file descriptor number. This number is the 
filenoO, defined in < stdio.h > , of the stream or the file number 
returned by open{). 


The memory allocation routines are malloc() and calloc(). The 
free() routine coalesces space which is returned, and the 
allocation system will reuse deallocated space. 

Program begin execution with 8 Kbytes of stack space 
available. This is sufficient for more applications. The C 
compiler, for example, uses less than 5 Kbytes. The size of 
the stack may be changed by declaring global variable 

^stksize and initializing that variable to the size of the stack 

required. For example: 

long stksize = 16384L 
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Since pointers are 32 bits long, a C program can use as much 
memory as is available on the machine through dynamic 
allocation. 

Before you use malloc or calloc, you must make the 
declaration: 

extern char ’malloc() 
extern char *calloc() 

If you fail to do this, the compiler will assume that malloc() or 
callocf) returns an int, which is only 16 bits wide. The 
declaration is included in < stdio.h > . 


Program parameters passed from the shell are available 
through the argc and argv program parameters to main(). For 
example: 

mainfargc, argv, envp) 
int argc; 
char 'argvO; 
char 'envpQ: 

argc is the number of strings in the argv array. argv[0] is not 
defined. If you do not need program parameters, declare 
main() without parameters, and the link will not load the code 
to retrieve them. 

envp is a pointer to a NULL terminated list of environment 
variables from the previous program, and is optional. 


The system library functions are listed alphabetically on the 
next page. On page 5.1-5 they are listed in functional groups. 
Detailed descriptions of each function are provided in section 
5.2. 
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The C system library functions are listed alphabetically below. 
Refer tn the page number indicated for a detailed description. 
The functions are listed by function on the next page. 


Command 

Paae 

Command 

—Page 

abs 

5.2-2 

isxdigit 

5.2-33 

alloca 

5.2-3 

Icailoc 

5.2-7 

atof 

5.2-4 

Imalloc 

5.2-36 

atoi 

5.2-5 

longjmp 

5.2-35 

atol 

5.2-5 

Irealloc 

‘5.2-49 

bcmp 

5.2-6 

Iseek 

5.2-34 

bcopy 

5.2-6 

malloc 

5.2-36 

bzero 

5.2-6 

onexit 

5.2-37 

calloc 

5.2-7 

open 

5.2-38 

clearerr 

5.2-8 

perror 

5.2-42 

close 

5.2-9 

printf 

5.2-39 

creat 

5.2-10 

putc 

5.2-43 

execi 

5.2-1 1 

putchar 

5.2-44 

execv 

5.2-12 

puts 

5.2-45 

exit 

5.2-13 

putw 

5.2-46 

fclose 

5.2-14 

qsort 

5.2-47 

terror 

5.2-15 

rand 

5.2-48 

feof 

5.2-16 

read 

5.2-49 

fflush 

5.2-17 

realloc 

5.2-50 

fgetc 

5.2-18 

rename 

5.2-51 

fgets 

5.2-19 

rewind 

5.2-52 

filenq ■ 

5.2-20 

rindex 

5.2-58 

fopen 

5.2-21 

scant 

. 5.2-53 

fprintf 

5.2-38 

setbuf 

5.2-56 

fputc 

5.2-22 

setbuffer 

5.2-56 

fputs 

5.2-23 

setlinebuf 

5.2-56 

fread 

5.2-24 

setjmp 

5.2-57 

free 

5.2-25 

sprintf 

5.2-39 

treopen 

5.2-21 

srand 

5.2-48 

fscanf 

5.2-52 

sscanf 

5.2-53 

fseek 

5.2-26 

strcat 

5.2-58 

fteil 

5.2-27 

strcmp 

5.2-58 

fwrite 

5.2-28 

strcpy 

5.2-58 

getc 

5.2-29 

strlen 

5.2-58 

getchar 

5.2-30 

strncat 

5.2-58 

gets 

5.2-31 

strncmp 

5.2-58 

getw 

5.2-32 

strncpy 

5.2-58 

index 

5.2-58 

strtol 

5.2-5 

isalnum 

5.2-33 

toascii 

5.2-60 

isalpha 

5.2-33 

tolower 

5.2-60 

isascii 

5.2-33 

tolower 

5.2-60 

iscntrl 

5.2-33 

toupper 

5.2-60 

isdigit 

5.2-33 

ungetc 

5.2-61 

islower 

5.2-33 

unlink 

5.2-62 

isprint 

5.2-33 

write 

5.2-63 

ispunct 

5.2-33 

xtrcat 

5.2-58 

isspace 

5.2-33 

xtrcpy 

5.2-58 

isupper 

5.2-33 

xtrncpy 

5.2-58 
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This section lists the functions in the C Library by function. 
Refer to the page number indicated for a detailed description. 


Command 

Pace 

Description 

close 

5.2-9 

Close a file 

creat 

5.2-10 

Create a file (old method-use open) 

Iseek 

5.2-34 

Reposition file 

open 

5.2-38 

Open a file 

read 

5.2-49 

Read data from file 

unlink 

5.2-62 

Delete a file 

write 

5.2-63 

Write data to file 

clearerr 

5.2-8 

Remove error state 

fclose 

5.2-14 

Close a stream 

feof 

5.2-16 

Test end of file 

terror 

5.2-15 

Test for error 

fflush 

5.2-17 

Write buffer to disk 

fgetc 

5.2-18 

Fast read byte 

fgets 

5.2-19 

Read string 

fileno 

5.2-20 

RIe associated with stream 

fopen 

5.2-21 

Open a stream 

fprintf 

5.2-39 

Formatted write 

fputc 

5.2-22 

Write byte 

fputs 

5.2-23 

Write string 

tread 

5.2-24 

Read data from stream 

treopen 

5.2-21 

Use different file with stream 

fscant 

5.2-53 

Formatted read 

tseek 

5.2-26 

Reposition stream 

ftell 

5.2-27 

Report position 

twrite 

5.2-28 

Write data to stream 

getc 

5.2-29 

Read byte 

getchar 

5.2-30 

Read byte from stdin 

gets 

5.2-31 

Read string from stdin 

getw 

5.2-32 

Read word 

printt 

5.2-39 

Formatted write to stdout 

putc 

5.2-43 

Fast write byte 

putchar 

5.2-44 

Write byte to stdout 

puts 

5.2-45 

Write word (integer) to the output stream 

putw 

5.2-46 

Write string to stdout 

rewind 

5.2-52 

Reposition stream to front 

scant 

5.2-53 

Formatted read from stdin 

setbut 

5.2-56 

Set buffer (standard size) 

setbuffer 

5.2-56 

Set buffer (any size) 

setlinebut 

5.2-56 

Set buffer mode 

sprintt 

5.2-39 

Formatted write to array 

sscant 

5.2-53 

Formatted read from array 

ungetc 

5.2-61 

Put byte back on stdin 

atot 

5.2-4 

ASCII to float 

atoi 

5.2-5 

ASCII to int 

atol 

5.2-5 

ASCII to long 

isalnum 

5.2-33 

Test for alphanumeric 
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isalpha 

5.2-33 

Test for letter 


isascii 

5.2-33 

Test for ASCII 


iscntrl 

5.2-33 

Test for control character 


isdigit 

5.2-33 

Test for digit 


islower 

5.2-33 

Test for lower case 


isprint 

5.2-33 

Test for printable character 


ispunct 

5.2-33 

Test for punctuation 


isspace 

5.2-33 

Test for white space 


isupper 

5.2-33 

Test for upper case 


isxdigit 

5.2-33 

Test for hex digit 


strtol 

5.2-5 

ASCII (any base) to long 


toascii 

5.2-60 

Int to ASCII 


tolower 

5.2-60 

Byte to lower case 


^tolower 

5.2-60 

Fast tolower 


toupper 

5.2-60 

Byte to upper case 

String Functions 

index 

5.2-58 

Find byte in string 


rindex 

5.2-58 

Find byte from end 


street 

5.2-58 

Append strings 


stremp 

5.2-58 

Compare strings 


strepy 

5.2-58 

Copy string 


strlen 

5.2-58 

Lenght of string 


strncat 

5.2-58 

Append n bytes 


strnemp 

5.2-58 

Compare n bytes 


strnepy 

5.2-58 

Copy n bytes 


xtreat 

5.2-58 

Append, but return end 


xtrepy 

5.2-58 

Copy, but return end 


xtrnepy 

5.2-58 

Copy n bytes, return end 

Memory Allocation 

alloca 

5.2-3 

Allocate on stack 


bemp 

5.2-6 

Compare two blocks of memory 


bcopy 

5.2-6 

Copy ablock of memory to another block 


bzero 

5.2-6 

Zeroes a block of memory 


calloc 

5.2-7 

Allocate and clear 


free 

5.2-25 

Release memory 


Icalloc 

5.2-7 

Allocate a lot and clear 


Imalloc 

5.2-36 

Allocate lots of memor 


Ireaiioc 

5.2-50 

Resize a lot of memoryy 


malloc 

5.2-36 

Allocate memory 


realloc 

5.2-50 

Resize allocated memory 

Miscellaneous 

abs 

5.2-2 

Absolute value of int 


longjmp 

5.2-35 

Non-local goto 


execi 

5.2-1 1 

Executes a file 


exeev 

5.2-12 

Execute a file 


exit 

5.2-13 

Terminate program 


onexit 

5.2-37 

Adds logic to exit function 


perror 

5.2-42 

Displays system error message 


qsort 

5.2-47 

Quick sort 


rand 

5.2-48 

Random number 


rename 

5.2-51 

Rename a file on disk 


setjmp 

5.2-57 

Non-local label 


srand 

5.2-48 

Start random sequence 
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5.2 C LIBRARY DESCRIPTION 

This section contains detailed descriptions of the standard C functions 
supported by the Chameleon 32 C Development System compiler. 
These functions are defined in the file llbc.a and are listed in 
alphabetical order. Refer to Section 5.1 for a list of the functions by 
page number. 
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abs 


Declaration 


Description 


#include <stdio.h> 

int abs (i) 
int I; 


abs returns the absolute value of the number that is the 
parameter. 
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alloca 

Declaration 


Description 


See Also 


char *alloca (size) 
unsigned int size; 


This function allocates size bytes of space in the stack frame 
of the calling function. This space is temporary and is 
automatically released upon the return of the calling function. 

alloca does not check for stack overflow. The size of the 

stack is set to the value in extern long stksize when the 

program starts (default is 8 kbytes). stksize should be 

redefined if more space is needed, 

mailoc, free, calioc 


Tekelec 


5.2-3 


Version 2.2 



Chameleon 32 C Manual 


Ch. 5.2: C Library Description 


atof 


Oeciaration 


Description 


Returns 


double atof (nptr) 
char ‘nptr; 


This function converts a character string pointed to by nptr to 
a double-precision floating-point number. The first 
unrecognized character ends the conversion, atof recognizes 
an optional string of white-spaced characters, then an 
optional sign, then a string of digits optionally containing a 
decimal point, then an optional E or e followed by an 
optionally signed integer. 


If the string begins with an unrecognized character, then a 
zero is returned 
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atoi, atol, strtol 


Declaration int atoi (str) 

char ‘str; 

long atoi (str) 
char *str; 

long strtol (str, ptr, base) 
char *str; 
char "^tr; 
int base; 


Description These functions convert strings to integers. 

strtol returns as a long integer the value represented by the 
character string str. The string Is scanned up to the first 
character inconsistent with the base. Leading white-space 
characters are ignored. 

If the value of ptr is not (char **) NULL, a pointer to the 
character terminating the scan Is returned in *ptr. If no integer 
can be formed, *ptr is set to str, and zero is returned. 

if base is positive and not greater than 36, it is used as the 
base for conversion. After an optional leading sign, leading 
zeros are ignored, and "Ox" or "OX" Is ignored if base is 16. 

Truncation from long to Int can take place upon assignment or 
by an explicit cast. 

atoi takes the ASCII representation of a number and converts 
it into a long integer. 

atoi takes the ASCII representation of a number and converts 
It into an integer. 
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bcmp, bcopy, bzero 


Declaration int bcmp(block1 , biock2, len) 

char *block1 , *block2; 
int len; 

int bcopy(source, destin, len) 
char "source, "destin; 
int len; 

int b 2 ero(block 1 , len) 
char "blocki ; 
int len; 


Description These functions perform operations on blocks of memory, 

bcmp compares two blocks of memory blocki and block2. 
The size of the blocks is ten. A value of 1 is returned if they 
are identical. 

bcopy copies the source block of memory to the block of 
memory pointed to by destin. Both blocks are of size len. 

bzero zeroes the memory pointed to by blocki. The block is 
of size len. 
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calloc, icalloc 

Declaration 


Description 


See Also 


Returns 


char*calloc (nelem, elsize) 
unsigned int neiem, elsize; 

char Icalloc (nelem, elsize) 
unsigned long nelem, elsize; 


calloc allocates space for an array of nelem elements of size 
elsize. The space is initialized to zeros. 

Icalloc is like calloc but accepts long parameters. 


malloc, free, alloca 


Return a null pointer if there is no available memory. 
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clearerr 

Declaration 


Description 


See Also 


#include <stdio.h> 

clearerr (stream) 
FILE 'stream; 


This function resets the error indicator and EOF indicator to 
zero on the named stream. This function is implemented as a 
macro and therefore cannot be declared or redeclared. 


feof, terror, fileno 
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close 


Declaration 


Description 


See Also 


Returns 


int close (tildes) 
int tildes; 


This tunction closes a tile, fildes is a tile descriptor obtained 
trom creat or open, close will tail it fildes is not a valid, open 
tile descriptor. 


creat, open 


0 - SuccesstuI 
-1 = Error 
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creat 

Declaration 

Description 


See Also 
Returns 


int creat (fname, oflag) 
char *fname; 
int oflag; 


This function creates a new file or writes to an existing one. If 
the file exists, the length of the file is reduced to 0. 

If successful, the file descriptor is returned and the file is 
opened for writing. The file pointer is set to the beginning of 
the file. 

oflag may be set to O BINARY to Indicate the untranslated 
mode. No other flag v^es are allowed here (see open). 

creat will fail if an OS error occurs. 

No process may have more than 12 files open simultaneously. 

This function has been superceded by open with the 
O CREAT flag. 


close 

File descriptor (non-negative Integer) = successful 
-1 = Error 
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execi 

Declaration 


Description 


See Also 


execi (name, argO, arg1, . . . , argn, OL) 
char "name; 

char *argO, arg1, . . . argn; 


This function executes a file. PATH is not evaluated from 
execi. For example, from the shell, you execute the cp (copy) 
program, as follows: 

%cp X y 

where: cp is argO, x is arg1 and y is arg2. 

In a program, you use execi to execute the cp program, by 
entering the following: 

execl(“\\bin\\cp” ,“cp” ,“x” , “y” , OL) 


where: WbinWcp is the path, cp is argO, x is arg1, and y is 
arg2. 

execv 
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execv 

Declaration 

Description 


See Also 


int execv (pathname, argv) 
char ‘pathname, *argv( ]; 


execv executes a program from the disk. The parameter 
pathname is a pointer to a string which contains the path and 
the name of the program to be executed. 

The argv parameter is necessary only if the program being 
started has arguments to main(). argv is an array of character 
pointers to strings, creating an argument list that is made 
available to the new program. When used, at least one 
argument must be present in this array, with the first element 
of the array being the name of the executed program. For 
more information, refer to the Program Parameters section at 
the beginning of Chapter 5. 

The parameter envp is also an array of character pointers to 
strings which are not command line arguments, but system 
environment variables. 

When the executed program begins, it is called as follows: 

main(argc, argv, envp) 
int argc; 
char ‘argvQ; 
char ‘envpQ; 

where argc, the arg count, is the number of elements in argv, 
and argv is the array of character pointers to the arguments 
themselves. 

The parameter envp is a pointer to an array of strings which 
are the environment variables from the calling program. Note 
that a pointer to this array is also stored in the global variable 
extern char "^environ. Each string consists of a name, an = 
sign, and a null-terminated value. The array of pointers is 
terminated by a null pointer. The result from execv is the exit 
code or status of the program. 


execi 
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exit, exit 

Declaration 


Description 


exit (status) 
int status; 


exit (status) 
irit status; 


These functions terminate a process. 

exit performs the following cleanup operations before 
terminating the program: 

• The onexit functions are called in the reverse order in 
which they were added 

• Ail open streams are flushed and closed 

• All remaining file descriptors (opened with open or creat) 
are closed 

• ^exit is called 

__exlt terminates the program immediately without performing 
any cleanup operations. 
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fciose 

Declaration 


Description 

See Also 


Returns 


#include <stdio.h> 

int fciose (stream) 
FILE 'stream; 


This function writes any buffered data to disk and closes a 
stream. It is called for each open stream by exit. 


fflush 


0 Successful 
EOF = Unsuccessful 


Tekelec 


5.2-14 


Version 2.2 





Chameleon 32 C Manual 


Ch. 5.2: C Library Description 


terror 

Declaration 


Description 


See Also 


#include <stdio.h> 
int terror (stream) 
FILE "stream; 


This function returns a non-zero when an I/O error has 
previously occurred reading from or writing to the named 
stream. Otherwise a zero is returned. This function is 
implemented as a macro and therefore cannot be declared or 
redeciared. 


clearerr, feof, fileno 
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feof 

Declaration 


Description 


See Also 


#include <stdio.h> 
int feof (stream) 
FILE 'stream; 


This function returns a non-zero when EOF has previously 
been detected reading the named input stream. Otherwise 
zero is returned. This function is implemented as a macro, 
and therefore cannot be declared or redeclared. 


clearerr, terror, fileno 
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ffiush 

Declaration 

Description 

See Also 
Returns 


#include < stdio.h > 

int ffiush (stream) 
FILE "stream; 


This function writes any buffered data to disk and clears the 
input buffer, but does not close the stream. 


fclose 


0 = Successful 
EOF = Unsuccessful 
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fgetc 

Declaration 


Description 


See Also 


int fgetc (stream) 
FILE 'stream; 


This function returns the next byte from the named input stram 
and positions the pointer ahead one byte in the stream, fgetc 
performs the same function as getc, however it is a true 
function. It is slower, but takes less space per invocation. 

EOF is returned when end-of-file or error is encountered. 


getc, getchar, getw 
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fgets 

Declaration 


Description 

See Also 
Returns 


#include <stdio.h> 
char fgets (s, n, stream) 
char *s; 
int n; 

FILE ‘stream; 


This function reads characters from the stream into an array 
pointed to by s, until n-1 characters are read, or a new-line 
character is read and transferred to s, or an EOF is 
encountered. The string is terminated with a null character. 


gets 

s = Successful 

If EOF is encountered and no characters have been read, 
then no characters are transferred to s and a null pointer is 
returned. 

If an error occurs, a null pointer is returned. Attempting to 
use this function on a file that has not been opened for 
reading, causes an error. 
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fileno 

Declaration 


Description 


See Also 


#include <stdio.h> 
Int fileno (stream) 
FILE *stream; 


This function fileno returns the integer file descriptor for the 
named stream. This function is implemented as a macro and 
therefore cannot be declared or redeclared. 


clearerr, feof, terror 
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fopen, 

Declaration 


Description 


Returns 


freopen 

#include <stdio.h> 

FILE *fopen (fiie name, type) 

char *file-name. Type; 

FILE Ireopen (file name, type, stream) 

char *flle name. Type; 

FILE "stream; 

fopen opens the file named by file name and associates a stream 
with it. It returns a pointer to the FTlE structure associated with the 
stream. file_name points to a character string that contains the 
name of the fiie to be opened, type is one of the following: 

r Open for reading 

w Truncate or create for writing 

a Append; open or create for writing at end of file 
r + Open for update (reading and writing) 

w + Truncate or create for update 

a* Random open for read or write; pointer wiil be 
repositioned to end of file for writing 

freopen substitutes the named file in place of the open stream. 
The original stream is closed whether the open succeeds or not. 
freopen returns a pointer to the FILE structure associated with 
stream. It is typically . used to attach the pre-opened streams 
associated with stdin, stdout, and stderr to other files. 

If a file is open for update, both input or output may be attempted 
on the stream. However, output may not be directly followed by 
input without an intervening fseek or rewind, and input may not be 
directly followed by output without an intervening fseek, rewind, or 
an input operation which encounters end-of-file. 

Files open for append cannot have information overwritten. All 
output is appended to the end of file regardless of the current 
pointer position. After output is completed, the pointer is positioned 
at the end of the file. 

fopen can be used to direct output to Chameleon 32 devices: .AUX 
(Serial Port 2 unformatted data), .TTY (Serial Port 2 formatted 
data), and .PRT (printer). For example; 

FILE ‘fp; 

fp » fopen C.AUX', 

fprintf (fp, "This Is unforaatted output to Serial Port 2”); 

Referencing the Chameleon hard disk directories requires the use 
of double back slashes as shown in the following example: 

f opeo( "a: WusrWhisf n e" , ■ r* ) ; 

If unsuccessful, these routines return a NULL pointer. 
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fputc 

Declaration 

Description 

See Also 

Returns 


#include <stdio.h> 
int fputc (c , stream) 
char c; 

FILE 'stream; 


fputc writes the character c to the output stream at the current 
pointer position. It is similar to putc but it is a true function, it 
is slower, and takes less space per invocation. 


putc, putchar, putw 


If successful, the value written is returned. 

if unsuccessful, EOF is returned. This can occur if the file is 
not open for writing, or if the output file cannot be grown. 
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fputs 


Declaration 


Description 


See Also 


Returns 


include <stdio.h> 
int fputs (s, stream) 
char *s; 

FILE ’stream; 


This function writes the null-terminated string, pointed to by 
s, to stream. The string is not followed by a new-line 
character. It does not write out the terminating null character. 


puts 


EOF is returned if an error occurs. This will happen if output is 
attempted to a file not open for writing. 
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fread 

Declaration 

Description 

Note 

See Also 
Returns 


#include <stdio.h> 

int fread (ptr, size, nitems, stream) 

char *ptr; 

int size, nitems; 

FILE ‘stream; 


This function is for binary input. It places into an array nitems 
of data read from the input stream beginning at ptr. The data 
items are a sequence of bytes of length size. 

Reading is stopped when an error occurs, end-of-file is 
encountered, or nitems of data have been read, fread places 
the pointer, if any, at the byte following the last byte read, if 
one exists. The contents of the stream are not changed. 

fseek or rewind must be called before switching between 
reading and writing on a stream that allows both. 


fwrite 


Returns the number of items. read, if a non-positive number 
is given for nitems, then a 0 is returned and nothing is read. 
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free 

Declaration 


Description 


See Also 


free (ptr) 
char *ptr; 


This function makes space, pointed to by ptr ('and formerly 
allocated by malloc, Imalloc, calloc or Icalloc,) available for 
further allocation, free does not affect the contents of the 
space. 


malloc, Imalloc, calloc, Icalloc, alloca 
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fseek 

Declaration 

Description 


See Also 
Returns 


#include <stdio.h> 

int fseek (stream, offset, ptrname) 

FILE ‘stream; 

long offset; 

int ptrname; 


This function sets the position of the next input or output 
operation on the stream. The new position is at the signed 
distance offset bytes from the beginning, from the current 
position, or from the end of the file, depending on the value of 
ptrname. ptrname has the following values: 

0 Offset from beginning of file 

1 Offset from current position in file 

2 Offset from end of file 

fseek undoes the effects of ungetc. After fseek, the next 
operation to the file may be either input or output. 


rewind, ftell 


0 = Successful 

Non-zero = Unsuccessful. This can occur if fseek is 
attempted on a file not open via fopen, or if it is used on 
something other than a file. 
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ftell 

Declaration 


Description 

See Aiso 


#include <stdio.h> 
long ftell (stream) 
FILE "stream; 


This function returns the offset of the current byte relative to 
the beginning of the file associated with the named stream. 


fseek, rewind 
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fwrite 

Declaration 

Description 

See Also 
Returns 


#include <stclio.h> 

int fwrite (ptr, size, nitems, stream) 

char *ptr; 

int size, nitems; 

FILE 'stream; 


This function is for binary output. It attempts to append 
nitems of data from the array pointed to by ptr to the named 
output stream. 

fseek or rewind must be called before switching between 
reading and writing on a stream that allows both. 


fread 


Returns, the number of items written. If a non-positive 
number is given for nitems, then a 0 is returned and nothing is 
written. 
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getc 

Declaration 


Description 


See Also 


Returns 


#include <stdio.h> 
int getc (stream) 
FILE ‘stream; 


This function returns the next byte from the named input 
stream and positions the pointer ahead one byte in stream, 
getc is a macro and cannot be used where a function is 
required. For example, a function pointer cannot point to it. 


getchar, fgetc, getw 


EOF is returned when end-of-file or error is encountered. 
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getchar 

Deciaration 

Description 

See Also 

Returns 


#}nclude <stdio.h> 
int getcharO 


getchar is a macro that returns the next character from the 
standard input stream, stdin. 

The character is returned to the program only after pressing 
Return. To get the character immediately, refer to the 
window interface functions in Section 5.4. 


getc, fgetc, getw 


EOF is returned when end-of-file or error is encountered. 
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gets 

Declaration 

Description 

See Also 
Returns 


#inclucie <stdio.h> 
char *gets (s) 
char *8; 


This function reads characters from the standard input stream, 
stdin, into the array pointed to by s, until an end-of-file or 
new-line character is encountered. The new-line character 
is discarded and the string is terminated with a null character. 


fgets 

s = Successful 

If EOF is encountered and no characters have been read, 
then no characters are transferred to s and a null pointer is 
returned. 

If an error occurs, a null pointer is returned. Attempting to use 
one of these functions on a file that has not been open for 
reading will cause an appropriate error. 
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getw 

Declaration 

Description 

See Also 
Returns 


int getw (stream) 
FILE *stream; 


getw returns the next word (integer) from the named Input 
stream. The file pointer is positioned at the next word. No 
special alignment is assumed. 

EOF is returned when end-of-file or error is encountered. 


getc, getchar, fgetc 


EOF is returned if end-of-file or an error is encountered. 
Since EOF is a valid integer, use feof or terror to check the 
success of getw. 
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isalnum, isalpha, isascii, 
isprint, ispunct, isspace, 

iscntrl, isdigit, islower, 

Isupper, isxdigit 

Declaration 

#include <ctype.h> 



int isainum(c) 


c is alphanumeric 


int isaipha(c) 


c is a letter 


int isascii(c) 


c is an ASCII character, code less than 
0200 


int iscntrl{c) 


c Is a delete character (0177) or an 
ordinary control character (less than 
040) 


int isdigit(c) 


c is a digit 


int islower(c) 


c is a lower case letter 


int isprint{c) 


c is a printing character, 040 (space) 
through 0176 (tilde) 


int ispunct(c) 


c is a punctuation character (neither 
control nor alphanumeric) 


int isspace(c) 


c is a space, tab, carriage return, new- 
line, or formfeed 


int isupper(c) 


c is an upper case letter 


int isxdigit 


c is a hexadecimal digit 


int c; 



Description 

These macros classify character-coded integer values. 
isascii is defined on all integer values; the other functions are 
defined where isascii is true and for EOF (-1). If the 
argument of any of these macros lies outside its domain, the 
result is undefined. 

Returns 

0 = True 

Non-zero = False 
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Iseek 

Declaration 


Description 


Returns 


long Iseek (tildes, offset, whence) 
int tildes; 
long offset; 
int whence; 


This function moves the read/write file pointer. It sets the file 
pointer associated with fildes, by offset from the position 
specified by whence, whence has the following values: 

0 Pointer set to offset bytes 

1 Pointer set to current position plus offset bytes 

2 Pointer set to file size plus offset bytes 

Iseek will fail and the pointer will remain unchanged if: 

• hides is not an open file descriptor 

• whence is an invalid value. 

• the resulting pointer position would be negative 


-1 Unsuccessful 

If successful, it returns the pointer position in bytes from the 
beginning of the file. 
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longjmp 

Declaration 


Description 


See Also 


#include <stdio.h> 

longjmp (env, val) 
jmp-buf env; 
int val; 


This function is a non-local goto. It is useful for dealing with 
errors and interrupts encountered in a low-level subroutine of 
a program. 

longjmp restores the environment saved by the last call of 
setjmp with the same env argument. After longjmp is called, 
program execution continues as if the corresponding call of 
setjmp had just returned the value val. 

longjmp cannot cause se^mp to return the value 0. if longjmp 
is invoked with a second argument of 0, setjmp will return 1. 
Ail accessible data have values as of the time longjmp was 
called. 

If longjmp is called when env was never primed by a call to 
setjmp, or when the last such call is in a function which has 
since returned, the result will be unpredictable. 


setjmp 
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malioc, Imailoc 


Declaration char *malloc (size) 

unsigned int size; 

char Imailoc (size) 
unsigned long size; 


Description This function returns a pointer to a block of at least size bytes 

aligned for any use. The size parameter limits the size of the 
block to 64K. 

Imailoc is like malloc but accepts a long parameter, allowing 
more than 64K bytes per allocation. 


See Also free, calloc, alloca 


Returns 


Returns a null pointer if there is no available memory. 
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onexit 

Declaration 

Description 


See Also 

Example 


onexit(f) 
int (*f) ( ); 


onexit allows the user to add logic to the exit{) function. 
When a program is terminated normally or abnormally (using 
"C, kill, or the Applications Selection menu), the exit{) function 
is called, which calls up to 10 functions defined by the user. 
These functions can be defined by giving the function pointer 
to onexitQ. This is shown in the example below. 


exit 


myexit () 

puts(“exiting”); 
main () 

onexit(myexit); 


Result: This will display the message exiting on the screen 

when the program is terminated. 
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open 

Declaration 


Description 


Returns 


#include <fcntl.h> 

int open (fname, oflag) 
char *fname; 
int oflag; 


This function opens a file for reading or writing as specified by 
oflag. fname points to a string containing the name of the file 
file, oflag values are constructed by ORing flags from the 
following list (only one of the first three may be used): 


O-RDONLY 

O-WRONLY 

0-RDWR 

0-BINARY 


Open for reading only. 

Open for writing only. 

Open for reading and writing. 

Open in binary (untranslated) mode. 

The ASCII line feed character (10 decimal) is 
usually considered to be the line separator 
character. Tekelec C considers a carriage 
return/line feed combination to be the line 
separator. In order to easily overcome this 
difference, the run time library automatically 
converts carriage return/line feed to line feed 
on input, and converts line feed to carriage 
return/line feed on output to files. 

This conversion occurs at a very low level 
within the library routines. Files can be 
opened in untranslated or binary mode by 
setting a flag when the open procedure is 
called. 


Upon completion, the file pointer is set to the beginning of the 
file. No process may have more than 12 file descriptors open 
simultaneously. 


If successful, the file descriptor is returned. 

If unsuccessful, -1 is returned and errno is set appropriately. 
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prlntf, fprintf, sprintf, _fprintf, _sprintf 


Declaration #include <stdio.h> 

int print! (format [ , arg] . . . ) 
char format; 


int fprintf (stream, format [ , arg] . . . ) 
FILE * stream; 
char format; 


int sprintf (s, format [ , arg] . . . ) 
char *s, format; 


int fprintf(stream, format, args) 
FILE 'stream; 
char format, 'args; 


int _sprintf(s, format, args) 
char *s, format, 'args; 


Description These functions print formatted output, as described below. 

All buffers passed to printf() are limited to 256 characters. 

printf places output on the standard output stream stdout. 

fprintf p\aces output on the named output stream. 

fprintf is like fprintf except the arguments are retrieved from 
tFe pointer args. 

sprintf places "output", followed by a null character (\0) in 
consecutive bytes starting at *s. It is your responsibility to 
ensure that enough storage is available. 

sprintf works like sprintf except the arguments are retrieved 
Trom the pointer args, which normally points into the stack. 

Each function returns the number of characters transmitted 
(not including \0 for sprintf), or a negative value if an output 
error was encountered. 
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Each of these functions converts, formats, and prints its args 
under control of the format. The format is a character string 
that contains two types of objects: 

• Plain characters are copied into the output stream 

• Conversion specifications results in fetching zero or 
more args 

The results are undefined If there are insufficient args for the 
format. If the format is exhausted while args remain, the 
excess args are ignored. 

Each conversion specification is introduced by the character 
%. After the %, the following appear in sequence: 

• On optional flag which modifies the meaning of the 
conversion specification. 

• An optional decimal digit string specifying a minimum 
field width. If the converted value has fewer characters 
than the field width, it will be padded on the left (or right, 
if the left-adjustment flag has been given), with spaces, 
to the field width. A leading zero indicates zeros should 
be used instead of spaces. 

• A precision which gives the maximum number of 
characters to be printed from a string, or the number of 
digits to be printed to the right of the decimal point for 
float or double. 

. • An optional 1 specifying that a following d, o, u, or x 
conversion character applies to a long integer arg. 

• A character indicating the type of conversion to apply. 

The only flag character is the minus sign (-). When used, 
the result of the conversion will be left justified within the field. 
A field width or precision may be * instead of a digit string. In 
this case, an extra integer argument provides the field width 
or precision. 

The conversion characters and their meanings are: 

d,o,u,x The integer arg is converted to signed decimal, 
unsigned octal, decimal, or hexadecimal notation 
respectively. The letters abcdef are used for x 
conversion. 
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f The float or double arg is converted to decimal 

notation in the style: 

[-] < digits > . < digits > 

where the number of digits after the decimal point is 
equal to the precision specification. If the precision is 
missing, six digits are output. If the precision is zero, 
no decimal point appears. 

For example, the float or double arg is converted to 
the style: 

[-] < digit > . < digits > E{ + 1-) < digits > 

where there is one digit before the decimal point and 
the number of digits after it is equal to the precision. 
When the precision is missing, six digits are output. 
If the precision is zero, no decimal point appears. 

c The character arg is printed. 

s The arg is taken to be a string (character pointer) and 
characters from the string are printed until a null 
character {\0) is encountered, or the number of 
characters indicated by the precision specification is 
reached. If the precision is missing, it will be taken to 
be infinite, so all characters up to the first null 
character are printed. A null arg will yield undefined 
results. 

% Print a %. No argument is converted. 

In no case does a non-existent or small field width cause 
truncation of a field. If the result of the conversion is wider 
than the field width, the field is simply expanded to contain the 
conversion result. Characters generated by printf and fprintf 
are printed as if putc had been called. 
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perror 

Declaration 


Description 


perror(s) 
char *s; 

extern int sys nerr; 

extern char *sys errIistO; 


perror writes a short description of the last error that set errno 
onto the standard stream stderr. The string s is printed first, 
then a colon, then the message and a newline. The string s 
is usually the narne of the program which called perror. 

perror should only be called when a function which sets errno 
indicates an error has occurred since errno is not cleared 
upon successful execution. 

The messages printed are stored in the array sys erriist and 
may be indexed by -errno (this is not compatible" with UNIX 
where errno is always positive). The number of entries in 
sys en'Iist iS stored in sys nerr. 
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putc 

Declaration 

Description 

See Aiso 
Returns 


#include <stclio.h> 
int putc (c , stream) 
char c; 

FILE ‘stream; 


putc is a macro that writes the character c to the output 
stream at the current pointer position. 


putchar, fputc, putw 


If successful, the value written is returned. 

If unsuccessful, EOF is returned. This can occur if the file is 
not open for writing or if the output file cannot be grown. 
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Declaration 

Description 

See Also 

Returns 


Manual 


Ch. 5.2: C Library Description 


#include <stdio.h> 
int putchar (c) 
char c; 


putchsu’ is a macro that is defined as putc(c, stdout). (putc is 
a macro that writes the character c to the output stream at the 
current pointer position. See previous page.) 


putc, fputc, putw 


if successful, the value written is returned. 

If unsuccessful, EOF is returned. This can occur if the file is 
not open for writing or if the output file cannot be grown. 
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puts 

Declaration 

Description 

See Also 
Returns 


include <stdio.h> 
int puts (s) 
char ‘s; 


puts writes the null-terminated string, pointed to by s, to the 
standard output stream stdout. The string is followed by a 
new-line character. It does not write out the terminating null 
character. 


fputs 


EOF is returned if an error occurs. This will happen if output is 
attempted to a file not open for writing. 
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putw 

Declaration 


Description 


See Also 


Returns 


#include <stdio.h> 
int putw (w, stream) 
Int w; 

FILE “stream; 


putw writes the word (integer) w to the output stream at the 
current pointer position, putw does not force even alignment 
on the file. 


putc, putchar, fputc 


If successful, the value written is returned. 

If unsuccessful, EOF is returned. This can occur if the file is 
not open for writing or if the output file cannot be grown. 

Because EOF is a valid integer, ferror should be used to 
check for error when using putw. 
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qsort 

Declaration 


Description 


Example 


qsort(base, nelem, width, compare) 

char *base; 

int nelem, width; 

int fcompare) (); 


qsort is an implementation of the quicksort algorithm. The 
parameter base is a pointer to the base of the data. The 
parameter nelem is the number of elements in the array. The 
parameter width is the width of each element in bytes. The 
parameter compare is a pointer to the comparison routine to 
be called. 

This user-defined function will be passed two arguments 
which are pointers to the elements being compared. This 
routine must return an integer less than, equal to, or greater 
than zero, since the first argument is to be considered less 
than, equal to, or greater than the second. 

The quicksort algorithm used is recursive. 


finclude <std1o.h> 

Int test(a, b) 

Int •a, •b; 

{ 

return ‘a - •b; 

} 

■a1n() 

{ 

int x[ 1003 , 1; 

for (1~0; KlOO; Create some randon data */ 

*[i] = rand(); 

qsort(x, 100, sizeof( int). test); 

for (i=0, i<100; i4-i-)/» Display sorted result •/ 
printfCXd •. x[i]); 

puts (Press RETURN to continue*); getchar () ; 

} 
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rand 

srand 

Declaration 


Description 


#include <stdio.h> 

int rand{) 

srand(seed) 
long seed; 


rand and srand are macros that function as simple random- 
number generators. 

rand uses a multiplicative congruential random-number 
generator. 

srand can be called at any time to reset the random-number 
generator to a new starting point. The generator is initially 
seeded with a value of 1 . 
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read 


Declaration 


Description 


Returns 


int read (tildes, but, nbyte) 
int tildes; 
char *but; 
unsigned nbyte; 


read attempts to read nbyte bytes trom the tile associated 
with Wdes into the butter pointed to by buf. 

tildes is a tile descriptor obtained by using an open or creat. 

read will tail it tildes is not a valid tile descriptor open tor 
reading, or it an operating system error occurs. 

it the O BINARY tiag is not set, lineteed/carriage return 
combinations are translated to lineteeds, except trom the 
keyboard. 


0 = EOF is reached. 

It successtui, a non-negative integer is returned indicating 
the number ot bytes actually read. 

It unsuccesstui, a -1 is returned and errno is set 
appropriately. 
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realloc, Irealloc 


Declaration char *realloc(ptr, size) 

char *ptr; 
unsigned size; 

char ^realloc(ptr, size) 
char "ptr; 

unsigned long size; 


Description These are RAM allocator functions, realloc changes the size 

of the block pointed to by ptr to size bytes and returns a 
pointer to the (potentially moved) block. Note that the data 
will remain unchanged, and any data defined beyond size will 
be lost. 

Irealloc is like realloc but accepts a long parameter. 


Returns A null pointer if the memory requested is not available. 
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rename 

Declaration 

Description 

Returns 


int rename (from, to) 
char “from, “to; 


rename changes the existing name of a file on a disk to 
another name. The parameter from is a pointer to the name 
of the current file on disk. The parameter to is a pointer to 
the new name for the file. 


1 Unsuccessful 
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rewind 

Declaration 


Description 


See Also 


#lnclude <stdio.h> 
rewind (stream) 
FILE ‘stream; 


rewind sets the position of the next input or output operation 
on the stream. The new position is at the signed distance 
offset bytes from the beginning, from the current position, or 
from the end of the file, rewind is equivalent to feee/c(stream, 
OL, 0), except no value is returned. 

rewind undoes the effects of ungetc. After rewind the next 
operation to the file may be either input or output. 


fseek, ftell 
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scant, fscanf, 


Declaration 


Description 


sscanf 


#inciude <stdio.h> 

int scant (format [ , pointer] . . . ) 

char “format; 

int fscanf (stream, format [ , pointer] . . . ) 
FILE “stream; 
char “format; 

Int sscanf (s, format [ , pointer] . . . ) 
char “s, “format; 


Each function reads characters, converts them according to a 
format, and stores the results in its arguments. The arguments 
consist of a control string format and a set of pointer 
arguments indicating where the converted input should be 
stored. 

scanf reads from the standard input stream stdin. 
fscanf reads from tiie named input stream. 
sscanf reads from the character string s. 

The control string may contain: 

• White-space characters (blanks, tabs, and new-lines) 
which cause input to be read up to the next non white- 
space character. 

• An ordinary character (not %), which must match the 
next character of the input stream. 

• Conversion specifications, consisting of the character % , 
an dptional assignment suppressing character *, an 
optional numerical maximum field width, an optional 1 
indicating the size of the receiving variable, and a 
conversion code. 
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A conversion specification directs the conversion of the next 
input field; the result is placed in the variable pointed to by the 
corresponding argument, unless assignment suppression was 
indicated by *. The suppression of assignment provides a way 
of describing an input field which is to be skipped. An input 
field is defined as a string of non-white-space characters; it 
extends to the next inappropriate character or until the field 
width, if specified, is exhausted. 

The conversion code indicates the interpretation of the input 
field, For a suppressed field, no pointer argument should be 
given. The following conversion codes are legal: 

% A single % is expected in the input at this point; no 
assignment is done. 

d A decimal integer is expected; the corresponding 
argument should be an integer pointer. 

h A short decimal Integer is expected, the 

corresponding argument should be a short pointer. 

o An octal integer is expected; the corresponding 
argument should be an integer pointer. 

X A hexadecimal integer is expected; the 

corresponding argument should be an integer pointer. 

e,f,g A floating point number is expected; the next field is 
converted accordingly and stored through the 
corresponding argument, which should be a pointer 
to a float. The input format for floating point 
numbers is an optionally signed string of digits, 
possibly with a decimal point, followed by an optional 
exponent field consisting of an e, or an E, followed 
by an optionally signed integer. 

s A character string is expected; the corresponding 
argument should be a character pointer pointing to an 
array of characters large enough to accept the string 
and a terminating \0, which will be added 
automatically. The input field is terminated by a 
white-space character. 
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Note 


Returns 


c A character is expected. The corresponding 

argument should be a character pointer. The normal 
skip over white space is suppressed in this case. To 
read the next non-space character, use 1s. If a field 
width is given, the corresponding argument should 
refer to a character array. The indicated number of 
characters is read. 

The conversion characters d, o, and x may be preceded by 1 
to indicate that a pointer to long rather than int is in the 
argument list. Also, the conversion characters e, f, and g may 
be preceded by 1 to indicate that a pointer to double rather 
than to float is in the argument list. 

scant conversion terminates at EOF, at the end of the control 
string, or when an input character conflicts with the control 
string. In the latter case, the offending character is left unread 
in the input stream. 

scant returns the number of successfully matched and 
assigned input items. This number can be zero in the event 
of an early conflict between an input character and the control 
string. If the input ends before the first conflict or conversion, 
EOF is returned. 

Trailing white space (including a new-line) is left unread 
unless matched in the control string. 


These functions return EOF on end of input and a short count 
for missing or illegal data items. 
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setbuf, setbuffer, setiinebuf 


Declaration #inclucie < stdio.h > 

setbuf (stream, buf) 

FILE ‘stream; 
char *buf; 

char buf[BUFSIZE]; 

setbuffer (stream, buf, bufsize) 
FILE ‘stream; 
char TDuf; 

setlinebuf(stream) 

FILE ‘stream 


Description Three types of buffering are available: 

• Unbuffered Information appears on the destination 

file or terminal as soon as written 

• Block buffered Many characters are saved up and 

written as a block. Normally, all files 
are block buffered. 

• Line buffered Characters are saved up until a 

newline is encountered. 

setbuf is used after a stream has been opened, but before it 
is read or written, it causes the character array pointed to by 
buf to be used instead of an automatically allocated buffer, if 
buf is a NULL character pointer input/output will be completely 
unbuffered. A constant BUFSIZ, defined in the < stdio.h > 
header file, tells how big an array is needed. 

setbuffer sets up a user-defined I/O buffer whose size is 
determined by the parameter bufsize. If buf is NULL, the I/O 
buffer will be completely unbuffered. This function should only 
be used after a stream has been opened, but before it has 
been read or written. 

setiinebuf changes stdout or stderr from block buffered or 
unbuffered to line buffered. Unlike setbuf and setijuffer, it can 
be used at any time that the file descriptor is active. 

if the space passed as buf cannot be freed (it was not 
allocated by malloc, for example), then the stream must be 
set to unbuffered before closing. 
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setjmp 

Declaration 


Description 


See Also 


#include <stdio.h> 

int setjmp (env) 
jmp but env; 


This is a non-local goto which is useful for dealing with 
errors and interrupts encountered in a low-level subroutine of 
a program, setjmp saves its stack environment in env (whose 
type, jmp buf, is defined in the <stdio.h> header file), for 
later use 5y longjmp. It returns the value 0. 


longjmp 
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strcat, strncat, strcmp, strncmp, strcpy, strncpy, 
strien, Incfex, rindex, xtrncat, xtrcpy, xtrncpy 


Declaration 

#include <string.h> 



char *strcat (s1 , s2) 
char *31 , *32; 

char *strcpy (s1 , s2) 
char *s1 , *s2; 


char ’atmcat {31 , 32, n) 
char *31 , *32; 
int n; 

char strncpy {s1 , s2, n) 
char *s1, *s2; 
int n; 


int 3 trcmp (3l , 32) 
char *31 , *32; 

int strlen (a) 
char *s; 


int 3trncmp (31 , 32, n) 
char *31 , *32; 
int n; 

char *xtrcat(s1 , s2) 
char *s1 , *s2; 


int index (3, c) 
char *3, c; 

char *xtrcpy(s1 , s2) 
char *s1 , *s2; 


int rindex (3, c) 
char *3, c; 

char *xtrncpy(s1 , s2) 
char *s1 , *s2; 

Description 

The3e function3 perform 3 tring operatione as deacribed 
below. The argumenta s1, s2, and c point to atringa (arraya 
of charactera terminated by a null character). The functiona 
strcat, strncat, strcpy, strncpy, xtrcat, xtrcpy, and xtrncpy all 
alter 3l. They do not check for overflow of the array pointed 
to by si. 


strcat appenda a copy of atring s2 to the end of atring si, and 
returnasf. 


xtrcat appenda but returna a pointer to the end of s7, pointing 
at the null byte. 


s^cat appenda at moat n charactera. 


strcmp comparea ita argumenta and returns an integer less 
than, equal to, or greater than 0, depending on whether si is 
lexicographically less than, equal to, or greater than s2. 
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strncmp makes the same comparison as strcmp, but looks at 
a maximum of n characters. 

strcpy copies string s2 \o s1, stopping after the null character 
has been copied. The result \s s1. 

xtrcpy copies but returns a pointer to the end of s1 . 

strncpy copies exactly n characters, truncating s2 or adding 
null characters to s7 if necessary. The result will not be null- 
terminated if the length of s2 is n or more. 

xtmcpy copies like strncpy, but returns a pointer to the end of 
s1. 

strlen returns the number of characters in s, not including the 
terminating null character. 

index returns a pointer to the first occurrence of c In string s. 
NULL is returned if c is not in s. 

rindex returns a pointer to the last occurrence of c in string s. 
NULL is returned if c is not in s. 
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toupper, 

Declaration 


Range 

Description 


toiower, -tolower, toascii 


#include <ctype.h> 

int toupper (c) 
int c: 

int toiower (c) 
int c; 

int ___tolower (c) 
int c; 

int toascii (c) 
int c; 


The range for toupper and toiower is -1 to 255. 


These functions convert characters as described below. 

If the argument for toupper is a lower case letter, the result is 
a corresponding upper case letter. It does not check for 
already upper case. 

If the argument for toiower is an upper case letter, the result 
is a corresponding lower case letter. Arguments other than 
the ones mentioned are returned unchanged. 

toiower is similar to toiower but has a smaller domain and is 
Taster. It requires an upper case letter as its argument. 
Undefined results occur if arguments are other than required. 

toascii returns the argument with all but the low order 7 bits 
set to zero. 
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ungetc 

Declaration 


Description 


Returns 


#inciude <stdio.h> 

int ungetc (c, stream) 
char c; 

FILE ‘stream; 


This function pushes the character c into the buffer 
associated with an input stream, c will be returned by the 
next read from that stream, c is returned and the stream is 
left unchanged. 

A read must be performed prior to the ungetc. c can be read 
by getc, getchar, fread, gets, fgets, fgetc, fscanf, and scant 

One character pushback is guaranteed, provided that 
something has been read from the stream. 

fseek erases all memory of inserted characters. 


If c equals EOF, ungetc does nothing to the buffer and returns 
EOF. 

EOF is returned if ungetc cannot irisert the character. 
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unlink 


Declaration 


Description 


Returns 


int unlink (fname) 
char ‘path; 


This function removes the directory entry pointed to by fname. 

The named file is unlinked unless the operating system 
returns an error (see errno). 


0 = Successful 

-1 = Error (errno Is set appropriately) 
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write 


Declaration 


Description 


Returns 


int wrlte(fildes, but, nbyte) 
Int tildes; 
char *buf, 
unsigned nbyte; 


This function writes on a file. It writes nbyte bytes from the 
buffer pointed to by bufXo the file associated with the fildes. 

fildes is a file descriptor obtained from a creat or open. 

Writing begins at the current pointer position and is 
incremented by the number of bytes actually written after 
returning from write. 

write will fail if an operating system error occurs. The pointer 
position will remain unchanged in this event. 

If the o BINARY flag is not set, linefeeds and returns are 
translate? to carriage returns (except to the screen). 


If successful, the number of bytes actually written is returned. 
If unsuccessful, -1 is returned and errno is set appropriately. 
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5.3 SYSTEM LIBRARY GLOBALS 


Introduction Table 5.3-1 below lists C global variables that are defined in 

libc.a. You can read these variables to determine information 
about the current virtual terminal (window), cursor, time, and 
other information. 

You must declare these variables as external, using the C 
extern command, before you can use them. These variables 
may be used; however, changing their values is only for 
experienced users. 


GLOBAL 

FUNCTION 


Returns the current virtual terminal number (vtnum) 

QQ|[Q|Q||Q2|^||||||||||||[| 

Returns the cursor position in the line 

int^echo mode 

Echoes on getchar 

int ^cr mode 

MapsCRtoCR LF 

int ctl_c__mode 

Allows Ctrl C to exit 

int curr__year 

Returns current year, which is set in the shell and is 
used by other programs. 

long tab ^width 

Returns the number of characters per TAB 

long tkey 

Returns the task key of the current program 

int close__vt_ok 

Indicates if it is OK to close the VT o exitQ 

char **environ 

Environment for environmental variables 

_initO 

Returns base address of current program 

char **argv 

Program args 

int argc 

Programs args count 


Table 5.3-1: System Library Globals 
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5.4 WINDOW INTERFACE FUNCTIONS 


Introduction The extended C library has additional Window Interface 

functions that enable you to control windows for your 
applications. The library includes: 

• Functions 

• Escape sequences 

Both of these features are described in this section. 
Definitions of escape sequences, key values and function 
declarations are in the file video.h. 


Standard Input/ 

Standard Output When your program starts, a window is assigned to you for 

standard input and output {stdin, stdout, stderr). The window 
number (vtnum) is in the external variable stdvt. 

If you want to use any of the window interface functions 
without opening another window, you should use this variable 
as the value returned from openvtQ. 

All the regular I/O functions (printf, getchar, etc.) will operate 
on the standard window. If you open your own window, you 

should overwrite stdvt with your window number, and then 

restore it. For regular usage without another window, you do 
not need to be concerned with these functions. 


VT100 Format You can use the Window Interface functions to address the 

screen, as follows: 

• Rows: 1-22 

• Columns: 1-80 

• Row 23 is reserved for the LED display, which can be 
set by calling the assignleds() function. 

• Row 24 is reserved for the window banner and cannot 
be accessed by the application or the library. 


Form Mode You can change a window to form mode, using the 

openformQ function. In form mode a full screen is available; 
there are no banner and LED lines. 
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Default Window 
Attributes 


When an openvtQ call is made, a default attribute is set with 
the following characteris ics: 

• Banner line with the name given in openvtQ 

• Cursor is in (1,1) position and is disabled 

• All characters will be written at the current cursor 
position 

• Any Escape sequences remain in effect until changed to 
a different one or to the default 


The window interface functions are described beginning on 
the following page. 
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assignleds 

Declaration 


Range 


Description 


assignlecis(vtnum, pleds, ledword) 
long vtnum; 
char *pleds; 
long ledword; 


vtnum Virtual terminal number which is the value returned 
by the fopen function. 

pleds Pointer to 80 characters which will appear on the 
LEDs line. 


ledword Bits 10-31 are reserved. 

Bits 0-9: If Bit i = 1 , LED i + 1 is on. 
If Bit i = 0 LED i + 1 is off 


This function creates or changes the LEDs for an application. 
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closeform 


Declaration 


Description 


See Also 


closeform(vtnum) 
long vtnum; 


This function releases the screen from form mode and returns 
to window mode. In other words, it restores the screen to it 
previous status. 


openform 
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ciosevt 

Declaration 


Description 


See Also 


closevt(vtnum) 
long vtnum; 


This function releases the virtual terminal. The virtual terminal 
is determined by the virtual terminal number (vtnum) which is 
a value returned by the openvt function. 


openvt, putvt 
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disablecur 


Declaration 


Description 


See Also 


disablecur(vtnum) 
long vtnum; 


This function causes the cursor to be invisible on the screen 
(default setting), vtnum is the virtual terminal number of the 
window returned by the fopen function. 


enablecur 
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enablecur 


Declaration 


Description 


See Also 


enablecur(vtnum) 
long vtnum; 


This function causes the cursor to be visible on the screen, 
vtnum is the virtual terminal number of the window returned 
by the openvt function. 


disablecur 
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Declaration 


Description 


See Also 


Ch. 5.4: Window Interface Functions 


unsigned char getch(vtnum) 
long vtnum; 


This function gets a character from standard input without 
waiting. If no character is available, it returns a OxFF. When 
standard input is used (not opened using the openvtQ 

function), the vtnum value is in stdvt. The characters are 

not echoed. 


getcwt 
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getcwt 

Declaration 


Description 


See Also 


unsigned char getcwt(vtnum) 
long vtnum; 


As with the getch function, this function gets a character from 
standard input. It does not return a value until a character is 
available. 

Note that if you use this function, you will have to force a key 
when killing the task from the shell. 

When stdio is used, the vtnum value is in stdvt. 


getch 
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openform 

Declaration 

Description 


See Also 

Returns 


long openformO 


This function puts the screen in non-window (form) mode of 
24 lines and returns the virtual terminal number (vtnum). It 
clears the screen and works in form mode using putvt() calls. 
Only one open form is allowed in the system, and therefore 
this function should be in response to a request from the user. 


closeform 


0 (the vtnum of the form window) 
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openvt 

Declaration 

Description 

See Also 

Example 


long openvt(pname) 
char ‘pname; 


This function assigns a virtual terminal to an application, 
pname is a 25-character null-terminated string which will 
appear on the window banner. The function returns the virtual 
terminal number (vtnum) which is referenced in other 
functions. 

The first 10 characters of the string constitute an escape 
sequence that defines the default foreground and background 
colors of the window. 


putvt, closevt 


long myvt; 

myvt = openvt(“\033[36m\033[44mMyWindow”); 


where: 


\033[36m defines the foreground color as cyan 
\033[44m defines the background color as blue 
MyWindow defines the text for the window banner 
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prndata 

Declaration 

Description 

See Also 


prndata(data) 
char 'data; 


This function sends data to the printer. 


endprint, selprn 
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putvt 

Declaration 


Description 


See Also 


putvt{vtnum, string) 
long vtnum; 
char ‘string; 


This function displays a string on a virtual terminal (window). 
The virtual terminal is determined by the virtual terminal 
number (vtnum) which is a value returned by the openvt 
function. 

The string is a maximum of 80 ASCII characters in VT100 
format. Esc sequences are defined. 


openvt, closevt 
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selprn 


Declaration selprn (device, br, bits, sb, par) 

long device, br, bits, sb, par; 


Description This function selects the parameters for outputing to a printer. 

Use the numbers indicated below to select the setting for 
each parameter. 

The default printer settings are: 

Parallel, 9600, 8 bits, 2 Stop bits. Even. 

device Printer type 1 Parallel 

0 Serial 

br Baud rate 3 300 

6 600 

12 1200 

24 2400 

48 4800 

96 9600 

192 19200 

bits Data Bits 0 5 bits 

2 6 bits 

1 7 bits 

3 8 bits 

sb Stop bits. 1 1 stop bits 

2 1 .5 stop bits 

3 2 stop bits 

par Parity 0 None 

1 Odd 

3 Even 


See Also endprint, prndata 
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WINDOW INTERFACE ESCAPE SEQUENCES 


Introduction The Chameleon 32 C Escape sequences are a subset of the 

VT1 00 Escape sequences and are listed in the table below. 

Note Where a value is required for the Escape sequence (indicated 

by Pn in the syntax) enter the ASCII value of the value. For 
example, to move the cursor up 7 seven lines, you would print 
the string Esc [7 a. In C you use use the enter the following: 

ppintf("\033[7a") 
where \033 represents the Esc key in octal. 


Esc Sequence 

Function 

Esc[Pna 

Move cursor up Pn lines 

Esc[Pnb 

Move cursor down Pn lines 

Esc[Pn c 

Move cursor right Pn columns 

Esc [Pnd 

Move cursor left Pn columns 

Esc[Pi;Pnf 

Move cursor to line Pi column Pn 

Esc[f 

Move cursor home 

Esc(PnL 

Insert Pn lines (lines below the cursor move down) 

EscfPnM 

Delete Pn lines (lines below the cursor move up) 

Esc[4h 

Insert mode 

Esc[4i 

Replace mode (default) 

Esc[lP 

Delete 1 character 

Esc[0K 

Erase to the end of the line 

EscfOJ 

Erase to the end of the screen 

Esc[2J 

Clear the screen 


Table 5.4-1: Window Interface Escape Sequences 
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Screen Attributes Use the following command to set the screen attributes (color, 

highlight, blink, reverse video, etc): 

Esc [ nn m 

where: nn is one of the attribute numbers listed in the table 
below. 


Attribute 

Number 

Attribute 

0 

Reset attributes (Underline, Reverse, Blink, 
Highlight) 

1 

Highlight 

4 

Underline 

5 

Blink 

7 

Reverse 

30 

Foreground Black 

31 

Foreground Red 

32 

Foreground Green 

33 

Foreground Yellow 

34 

Foreground Blue 

35 

Foreground Magenta 

36 

Foreground Cyan 

37 

Foreground White 

40 

Background Black 

41 

Background Red 

42 

Background Green 

43 

Background Yellow 

44 

Background Blue 

45 

Background Magenta 

46 

Background Cyan 

47 

Background White 


Table 5.4-2: Window Interface Attribute Options 
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5.5 MATH LIBRARY 


Introduction The libm.a library includes the math functions described in this 

section. The libm.a library is in the \lib directory. When 
compiling a program, V/bV/b is automatically searched for 
library files, so that you can compile a program using libm.a 
by entering either: 

cc prog.c \lib\libm.a • 

or 

cc progc. -Im 

The format of a double precision floating point number is: 

• The leftmost bit (63) is the sign for the mantissa 

• The next bit (62) is the sign for the exponent 

• The next 10 bits (61 - 52) contain the binary exponent, 
which has a bias of 0x3ff (1023) 

• The mantissa (in bits 51 - 0) is preceded by an implied 
1-bit (left of the binary point). Therefore, the theoretical 
precision is 53 xiogio(2) = 15.95 decimal digits. 

All intermediate floating point operations are done in double 
precision. The transcendental functions use radians. 


Zero A zero is represented by all zeros In the floating point 

variable. 


Largest Value The largest possible value for a float variable is contained in 

the math library variable double dcsu. The value of this 
variable is OX Tfffffffffffffff. 


Infinity The value of infinity is represented by the math library variable 

double dcin. The value of this variable is 0 x ffffffffffffffff. This 
value is returned in the instances where a floating point 
operation exceeded the maximum value of a double floating 
point number. 
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Smallest Value 


The smallest number x > 0 is: 

X = 0x0000000000000001 
= ((1 +(2-52))(21025) 

= 1.11 25369292536009 x 1 0-308 

If the absolute value of a result is smaller than this number 
(called underflow), a zero is returned. 

The routines are described on the following page. 


Tekelec 


5.5-2 


Version 2.2 




Chameleon 32 C Manual 


Ch. 5.5: Math Library 


Declaration 


#include <math.h> 

Base e logarithm function 
Base 10 logarithm function 
Base 2 logarithm function 

Base e exponential function 
Base 10 exponential function 
Base 2 exponential function 

Transcendental functions 


double asjn(x), acos(x), 

atan(x) Inverse transcendental 

double sqr(x) 
double sqrt(x) 

x2 

Vx 

double powerd(x, y) 
double poweri(x,a) 

xy (equivalent to exp2(x1og2(y)) 
xa (equivalent to exp2(x*Iog2(a)) 
where a is an integer) 

double dabs(x) 

1x1 

int dint (x) 

Integer part of the double that is 
the parameter. The fractional 
part is truncated. This is 
equivalent to: 


sgn(x) X LIxlJ 


where: sgn(x) =-1, if x<0; 

= 0. ifx = 0: 

= 1. if x>0 

double mulpower2(x, k) 

Performs a fast floating point 
multiplication by 2^. 

double Ingamma(x) 

Natural logarithm of the gamma 
function if 0 <x< 5.1 x 10305. 
Outside of this range dcin 
(infinity) is returned. 

double fac(/() 

k\, where 0</c<170 


double log(x) 
double loglO(x) 
double log2(x) 

double exp(x) 
double expl 0(x) 
double exp2(x) 

double sin(x), cos(x), tan(x) 


double x,y; 
int a, k; 
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double matinv(a, c, n) 
double "a; 
long *0; 
long n; 

matinv is the matrix inverse of the nxn array a. The data in a 
may be stored in either row or column major order (C double 
dimension arrays are row major), c is a vector {one 
dimensional array) of longs used during the computation, 
matinv returns the determinant of a as the function result, and 
the Inverse of a in a. c has no meaning after matinv finishes. 
A determinant value of zero indicates failure (a is destroyed). 

For example: 


#1iic1ude <aath.h> 


double e[2] [2] = {1.0,0. 1}; /•Identity Matrix*/ 

■ain() 

{ 

double det; 
long €[2] 

det-oat1nv(e, C» 2L); 

pr1ntf(*The deteniinant of e is Xf\n", det); 

) 
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5.6 CONTROL CHARACTERS 

Introduction The control characters are listed in the table below. 


Control 

Character 

Control Key 

Function 

BEL (7) 

Ctrl G 

Bell 

BS (8) 

Ctrl H 

Back Space 

LF (10) 

CtrlJ 

Line feed 

VT(11) 

Ctrl K 

Move cursor down 1 line 

FF (12) 

Ctrl L 

Move cursor forward 1 character 

CR (13) 

CtrIM 

Carriage return 


Table 5.5-1: Control Characters 
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5.7 USING AUX SERIAL PORTS 1 & 2 


Introduction The C Development System includes functions for accessing the 

Aux Serial Ports 1 and 2. There are four functions for each port. 
Those for Port 1 are: 

• initportb Initializes the Aux Serial Port 1 . You must use 

this function to initialize the port before you can 
transmit or receive. 

• sndpb Transmits data using Aux Serial Port 1 to another 

device 

• recpb Receives data using Aux Serial Port 1 from 

another device 

• rstdrvb Flushes the driver reception buffer. 

Port 1 is only available if the debugger is not attached to it. For 
details on the debugger, see Chapter 2. 1, Configuration File. 

Those for Port 2 are: 

• initporta Initializes the Aux Serial Port 2. You must use 

this function to initialize the port before you can 
transmit or receive. 

• sndpa T ransmits data using Aux Serial Port 2 to another 

device 

• recpa Receives data using Aux Serial Port 2 from 

another device 

• rstdrv Flushes the driver reception buffer. 

These functions are described on the following pages. The Port 1 
functions are given on pages 5.7-2 through 5.7-5. The Port 2 
functions are given on pages 5.7-7 through 5.7-10. Sample 
programs are provided on pages 5.7-6 and 5.7-11 . 
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PORT 1 FUNCTIONS 


initportb 


Declaration #include “paval.h 

int initportb {stopbit, bitchar, bitrate, parity) 
long stopbit; 


long bitchar; 
long bitrate; 
long parity; 

Ranges stopbit 


bitchar 


bitrate 


parity 


ST1 

(1 stop bit) 

ST15 

(1.5 stop bits) 

ST2 

(2 stop bits) 

DBS 

(5 data bits) 

DB6 

(6 data bits) 

DB7 

(7 data bits) 

DBS 

(8 data bits) 

F110 

(110 bits per second) 

F300 

(300 bits per second) 

F120 

(1200 bits per second) 

F240 

(2400 bits per second) 

F480 

(4800 bits per second) 

F960 

(9600 bits per second) 

FI 92 

(19200 bits per second) 

PANO 

(No parity) 

PAEV 

(Even parity^ 

PAOD 

(Odd parity) 


Description This function initializes the Chameleon 32 Aux Serial Port 1 to 

transmit and receive data. When you use initporta, the driver 
reception buffer is automatically flushed. 


Returns 0 Successful 

-1 Parameter error 

-2 Port 1 not available 


Tekelec 


5.7-2 


Version 2.5 




Chameleon 32 C Manual 


Ch. 5.7: Using Aux Serial Ports 1 & 2 


sndpb 


Declaration #include “paval.h” 

int sndpb (ptr, nb, timeout) 
char ptr; /‘user buffer pointer*/ 

long nb; /‘number of bytes*/ 

long timeout; /‘timout value*/ 

Description This function transmits data using Aux Serial Port 1 . You must first 

initialize the port using the iniportb function, before you can 
transmit or receive data using this port. 

ptr is a pointer to a buffer containing the data to transmit, nb is the 
number of bytes of data to transmit, timeout is the amount of time 
to wait for the other device to receive the data. It is in millisecond 


Returns 

units. 

nb 

Number of bytes transmitted 


0 

Time out 


-1 

Parameter error 


-2 

Port 1 not available 
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recpb 

Declaration 


Description 


Returns 


#include “paval.h” 
int recpb (ptr, timeout) 
char *ptr; 
long timeout; 

This function receives data using Aux Serial Port 1. You must first 
initialize the port using the iniportb function, before you can 
transmit or receive data using this port. 

pfr is a pointer to a buffer to put the received data. 

f/meouf determines the amount of time to wait to receive data data 
in millisecond units. 

If timeout > 0, the function immediately returns the number of 
characters currently in the reception buffer. If the reception buffer 
is empty, it waits the timeout period before returning the number of 
bytes or a timeout. 

If timeout = 0 the function immediately returns the number of 
characters currently in the reception buffer. If the buffer is empty, 
the Chameleon waits until a character is received before returning 
the number of bytes. 

nb 
0 
-1 
-2 


Number of bytes received 

Time out (no characters in the reception buffer) 

Parameter error 

Port 1 not available 
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rstdrvb 


Declaration 


Description 


Returns 


#inclucle “paval.h” 
rstdrvbO 

This function flushes the driver reception buffer. Note that the 
/n//)Dortb function automatically flushes the driver reception buffer 
when the port is initialized. 

-2 Port 1 not available 
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SAMPLE PROGRAM 


A sample program using the Aux Serial Port 1 functions is provided 
below. This program initializes the port for terminal emulation. 


finclude "paval . h" 
extern long stdvt ; 


/* 

Terminal em 

main 0 


{ 


char 

rbuf[300] ; 

char 

dbuf[300] ; 

char 

c ; 

int 

len ; 

int 

i/j ; 




/* reception buffer */ 

/* display buffer */ 

/* typed character */ 
/* number of data received */ 
/* local variables */ 
puts (^Terminal Emulation program^ Type ESC to exit'') ; 

/* Initialization of the port 

1 stop bit 

8 bits per characters 
bit rate = 9600 
No parity 




initportb {ST1/DB8,F960^ PANO) ; 
for(;;) 

{ 

/* poll local keyboard/ echo char and send char 


if ( {c=getch( stdvt)) !* -1 ) 


{ 

if ( c 
else 


« Oxlb ) 
break ; 

{ 

putvtsd (_stdvt/ &C/ IL) ; 
sndpb {&C/ IL/ lOL) ; 

} 


/* exit with ESCAPE */ 


} 


/* poll reception on AUX 1 port and display */ 

else if ( (len = recpb (rbuf , lOOL) ) != 0 ) 

{ 

for (i=*0/ j— 0;i!=len;i++) 

{ 

if ( rbuf[i] >— ' ' ) 

dbuf[j++] rbuf[i] ; 

} 

putvtsd (_stdvt/ dbuf / (long) j) ; 

) 

} 

}puts ("XnDisconnected") ; 

} 
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PORT 2 FUNCTIONS 


initporta 



Declaration 

#include “paval.h” 

int initporta (stopbit, bitchar, bitrate, parity) 

long stopbit; 

long bitchar; 

long bitrate; 

long parity; 

Ranges 

stopbit ST1 

ST15 

ST2 

(1 stop bit) 

(1.5 stop bits) 

(2 stop bits) 


bitchar DBS 

DB6 

DB7 

DBS 

(5 data bits) 

(6 data bits) 

(7 data bits) 

(8 data bits) 


bitrate F110 

F300 

F120 

F240 

F480 

F960 

F192 

(110 bits per second) 

(300 bits per second) 

(1200 bits per second) 

(2400 bits per second) 

(4800 bits per second) 

(9600 bits per second) 

(19200 bits per second) 


parity PANO 

PAEV 
PAOD 

(No parity) 

(Even parity) 

(Odd parity) 

Description 

This function initializes Aux Serial Port 2 to transmit and receive 
data. When you use initportb, the driver reception buffer is 
autornaticaliy flushed. 

Returns 

0 Successful 

-1 Parameter 

error 
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sndpa 

Declaration 

Description 

Returns 


#include “paval.h” 

int sndpa (ptr, nb, timeout) 

char *ptr; /*user buffer pointer*/ 

long nb; /‘number of bytes*/ 

long timeout; /*timout value*/ 

This function transmits data using Aux Serial Port 2. You must first 
initialize the port using the iniporta function, before you can 
transmit or receive data using this port. 

pfr is a pointer to a buffer containing the data to transmit, nb is the 
number of bytes of data to transmit, timeout is the amount of time 
to wait for the other device to receive the data. It is in millisecond 
units. 

nb Number of bytes transmitted 

0 Time out 

-1 Parameter error 
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recpa 

Declaration 

Description 


Returns 


#include “paval.h” 
int recpa (ptr, timeout) 
char *ptr; 

long timeout; 

This function receives data using Aux Serial Port 2. You must first 
initialize the port using the iniporta function, before you can 
transmit or receive data using this port. 

ptr is a pointer to a buffer to put the received data. 

f/meouf determines the amount of time to wait to receive data data 
in millisecond units. 

If timeout > 0, the function immediately returns the number of 
characters currently in the reception buffer. If the reception buffer 
is empty, it waits the timeout pjeriod before returning the number of 
bytes or a timeout. 

If timeout = 0 the function immediately returns the number of 
characters currently in the reception buffer. If the buffer is empty, 
the Chameleon waits until a character is received before returning 
the number of bytes. 

nb 
0 
-1 


Number of bytes received 

Time out (no characters in the reception buffer) 

Parameter error 
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rstdrv 

Declaration 

Description 


#include “paval.h” 
rstdrvO 

This function flushes the driver reception buffer. Note that the 
initporta function automatically flushes the driver reception buffer 
when the port is initialized. 
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SAMPLE PROGRAM 


A sample program using the Aux Serial Port 2 functions is provided 
below. This program initializes the port for terminal emulation. 


#include "paval . h'' 
extern long _stdvt ; 


/* 

Terminal emulation program 

main () 

{ 

char 

rbuf [300] ; 

/* reception buffer */ 

char 

dbuf[300] ; 

/* display buffer */ 

char 

c ; 

/* typed character */ 

int 

len ; 

/* number of data rece: 

int 

i/j ; 

/* local variables */ 


puts (''Terminal Emulation program. Type ESC to exit") ; 

1 '*^ Initialization of the port 

1 stop bit 

8 bits per characters 
bit rate = 9600 
No parity 


initporta (STl, DBS, F960, PANO) ; 
for ( ; ; ) 




{ 

/★ poll local keyboard, echo char and send char 


if ( (c=getch{__stdvt) ) != -1 ) 

{ 


if ( c == Oxlb J. 

break ; 

else 

{ 


/* exit with ESCAPE */ 


putvtsd (_stdvt, &c, IL) ; 
sndpa (&c, IL, lOL) ; 

} 


} 


/* poll reception on AUX 2 port and display */ 

else if ( (len = recpa (rbuf , lOOL) ) != 0 ) 

{ 

for (i=0, j='0;i!==len;i++) 

{ 

if ( rbuf[i] >* ' ' ) 

dbuf[j++] = rbuf[i] ; 

} 


putvtsd (_stdvt,dbuf, (long) j) ; 

} 


} 


Iputs ("\nDisconnected") ; 

} 


Tekelec 


5.7-11 


Version 2.5 






Chameleon 32 C Manual 


Ch. 5.8: MS-DOS File Functions 


5.8 MS-DOS COMPATIBLE RLE FUNCTIONS 


Introduction The Chameleon MTOS-UX file system Is designed to be 

compatible with MS-DOS 2.x and 3.x. The functions described 
in this section have been added to provide low-level access to 
the Chameleon file system. 


File Names The format of a filename is set by the system to be eight bytes 

in length, plus a three-byte extension. The set of characters 
allowed in a filename and extension are: 

A-Z, 0-9, - _!©#$%*&()” "{} 

Ail filenames must be terminated with a NULL (0x00) 
character. 


Wild Card 

Characters The question mark can be used as a wild card to describe 

multiple files having similar names. A wild card character can 
be used only in the search function. When used with other 
functions, it may produce incorrect results. 

The question mark is a single character wild card. For 
example, if you have three files named test1 .txt, test2.txt, and 
test3.txt, they could be identified simultaneously by using the 
name test7.txt. 


Directories The C library contains functions for creating and removing file 

directories and subdirectories. This enables you to have a 
hierarchical directory structure to provide a higher order of 
organization of files on the drive. 


Pathnames The use of pathnames enables you to access a drive or 

directory other than the current one. A filename is composed 
of the drive name and the directory specifiers as described 
below. 

The format of a pathname Is as follows: 

drive:\directory\directory\...filename 

drive is Chameleon disk drive you want to access, and is one 
of the following: 
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File Functions 


Sample Usage 


a: hard disk drive 

b: floppy disk drive 

You do not need to specify the drive if you want to access the 
current drive. 

Following the drive, you specify the hierarchy of directories 
necessary to access the desired directory. Each directory 
name is followed by the back slash (\) character. If a directory 
is not specified, the current directory is assumed. 

Following the directory path list is the file name of the files you 
want to access. This must include the file extension. The wild 
card ? can be used to specify more than one file narne. 


The standard C library (lib.c) contains the following MS-DOS 
compatible file functions: 

Fmkdir Makes a new directory 

Frmdir Removes a directory 

Fsearch Searches for a specified file or directory 

These functions are described on the following pages. 


Sample programs are provided beginning on page 5.8-7 to 
illustrate the usage of the file functions. 
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Error Codes When a file function is completed, it returns either 0 for 

success, or a negative number if an error has occurred during 
the execution of the function. 

The table below lists the possible codes: 


ErrorCode 

Description 

0 

Successful 

-1 

Configuration error 

-2 

Opcode error 

-3 

Parameter error 

-4 

Error in volume access 

-5 

RIe not found error 

-6 

RIe already exists error 

-7 

Queue empty 

-8 

Physical read error 

-9 

Physical write error 

-10 

Directory full error 

-11 

RIes open on directory 

-12 

RIe aready open 

-13 

Error in filename 

-14 

RIe locked 

-16 

Function option error 

-16 

Attribute error 

-17 

End of file unexpected error 

-18 

EOF with partial record 

-19 

Fatal error 

-20 

Disk full - Temporary 


Tekelec 


5.8-3 


Version 2.3 






Chameleon 32 C Manual 


Ch.'S.S: MS-DOS File Functions 


Fmkdir 

Declaration 

Description 

Returns 

Example 


#include <msfsuse.h> 
Fmkdir{dirname) 
char * dirname; 


This function creates a directory with the name dirname. 
dirname is a pointer to the directory name and can include 
the path for the new directory. 


See error codes on page 5.8-3. 


if ‘(Fmlcdir ( " . WabcWdef " ) ! » 0) { 

puts ("make dir error"); 


Also see sample programs beginning on page 5.8-7. 
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Frmdir 

Declaration 

Description 

Returns 

Example 


#include <msfsuse.h> 
Frmdir(clirname) 
char * dirname; 


This function removes a directory with the name dirname. 
dirname is a pointer to the directory name and can include 
the path to the directory. 

The directory must be empty before it can be removed from 
the disk. 


See error codes on page 5.8-3. 


if‘(Frmdir ( " . WabcWdef " ) ! = 0) { 

puts ("remove dir error"); 


Also see sample programs beginning on page 5.8-7. 
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Description 


Returns 

Example 


Ch. 5.8: MS-DOS File Functions 


#include <msfsuse.h> 
Fsearch(name, option, rec) 
char * name; 
int option; 
struct DREC *rec 


This function searches for a file or directory specified by 
name, name is a pointer to the file/directory name and can 
also include the path. 

If located, the file information is copied to the structure of type 
DREC, which is defined in msfsuse.h, as shown below: 


struct DREC 

char 

char 

char 

char 

unsigned short 
unsigned short 
unsigned short 
unsigned long 


dc_fn[ ]; 

dc ex[ ]; 

dc at; 

dc rs[ ]; 

dc ^tim; 

dc dat; 

dc str; 

dc fsz; 


/*File name*/ 

/"File extension*/ 

/"File attributes*/ 

/"Reserved bytes*/ 

/Time of file creation*/ 
/"Date of file creation*/ 
rstarting cluster number*/ 
/"File size in bytes*/ 


File attributes are defined in msfsuse.h as follows: 


FA_RDF 0x01 
FA_HDF 0x02 
FA_SYS 0x04 
FA_VOL 0x08 
FA_SDR 0x10 
FA ARF 0x20 


Read Only File 
Hidden File 
System File 
Volume 
Sub-directory 
Archive 


See error codes on page 5.8-3. 


See sample programs beginning on page 5.8-7. 
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Sample Usage 


The following sample programs demonstrate the use of the 
MS-DOS compatible file functions. Error messages printed by 
the programs are defined in a program named msfsmsg.c 
and declared in the file msfsmsg.h, which are not included in 
these samples. 

The first sample program creates a directory named test dir, 

searches for it, and then removes it. 


finclude 

<stdio.h> 

finclude 

<video.h> 

#include 

<asfsuse.h> 

#include 

*asfsasg.h* 

aain () 

{ 


char ^naae; 

int a; 


naae= •test_dir*; 

If ((a^Fakdlr(naae)) SUCCESS) { 

puts (*F«kdir completed successfully”); 
1s_searcti (naae); 

} 

else { 

pr1ntf(*Fflkdir Error: Xs*, asfsasg [-a] ); 
exit (0); 

} 

printf ("Hit a key to reaove test directory*); 
f flush (stdout); 

9 etc«t(_stdvt); 

if ((a»Fr«dir(naee)) == SUCCESS { 

puts ("Fradir coapleted successfully*); 

Is search(naae); 

else { 

printf(*Fradir Error: Xs*, asfsasg [-a] ); 

} 

printf (*\n6oodbye\n*); 

} 

ls_search(naae) 
char *naae ; 

{ 

struct OREC ayrec; 
int a; 

if ((a-Fsearch(naae, 0, &ayrec)) SUCCESS) { 
puts (*Fsearch coapleted successfully*); 

Is _print (&ayrec); 

} 

else { 

printf (*Fsearch Error: Xs*, asfsasg [-a] ); 

} 

} 


Tekelec 


5.8-7 


Version 2.3 





Chameleon 32 C Manual 


Ch. 5.8; MS-DOS File Functions 


The second sample program illustrates how to search for a 
specified file/directory. This program locates all items of the 
specified name on the drive. 


finclude <stdio.h> 

#inc1ude <video.h> 

#1nc1ude <Bsfsuse.h> 

#1ficlude *ssfsasg.h* 

■ain (argc, argv) 
char ♦•argv ; 

{ 

struct DREC ayrec; 
char buf [80]; 
int a, b,; 
if (argc ! * Z) 

strcpy (buf, *.■); 
else 

strcpy (buf, argv [1]); 
for (a * 0; ; a-w-) { 

printf ("Pass # Xd\n*, a+1); 
if (a > 0) { 

printf ( •\033[la— liORE — \033[0a"); 

f flush (stdout); 

getc«t(_stdvt); 

puts(**); 

} 

if ((b » Fsearch (buf, (a=*0?0:l).&iyrec))**SUCCESS) { 

puts ("Fsearch coapleted successfully*); 
ls_print (tayrec); 

} 

else { 

printf ("Fsearch Error: Xs\n*, asfsasg [-b]); 
break; 

} 

} 

} 
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This third program illustrates how the information resulting 
from the file search function can be displayed for the user. 

#inc1ude <asfsuse.h> 
ls_print (rec) 
struct DREC ^rec; 

{ 

int a; 

printf ("file name == XsXn*. rec-> dc_fn); 
prlntf ("file extension ** Xs\n*, rec-> dc_ex); 
printf ("file attributes =* X02x\n*, rec-> dc_at); 

If ((rec-> dc^at & FA^ROF) == FA^ROF) 
puts ("Read Only file*); 

else 

puts(*Read Write*); 

If ((rec-> dc_at & FA^HDF) == FA^HOF) 
puts ("Hidden file*); 

else 

puts ("Hot Hidden file*); 

If ((rec-> dc^at & FA^SYS) == FA_SYS) 
puts(*Syste« file*); 

else 

puts ("Mot Systea file*); 

If ((rec-> dc^at & FA VOL) == FA_VOL) 
puts ("Voluae bit == 1*); 

else 

puts ("Voltiae bit — 0*); 

If ((rec-> dc_at & FA^SOR) =* FA^SOR) 
puts ("Sub-directory file*); 

else 

puts ("Mot a Sub-directory file*); 

If ((rec-> dc_at & FA^ARF) == FA_ARF) 
puts ("Archive file*); 

else 

puts ("Mot Archive file*); 
printf ("reserved bytes ** "); 
for (a*0; a < RS^LEH; a^) 

printf (*X02x *, rec-> dc_rs [a]); 
puts (*•); 

printf ("tiae file was created— *); 

ls_t1ae (rec-> dc tia); 

puts(**); 

printf ("date file was created== *); 

Is tiae (rec-> dc_dat); 
puts(**); 

printf ("starting cluster nuaber == X04x\n*, rec-> dc_str); 
printf ("file size (bytes) == X-101d\n*, rec-> dc_fsz); 

} 

ls_t1ae (tiae) 

Int tiae; 

{ 

Int hrs = (t1ae»ll) &0xlf; 

Int aln > (t1ae»5) &0x3f; 

int sec = ((tiae) &0xlf) "2; 

if (hrs »= 0) 

hrs = 12; 

printf(*X02d:X02d:X02d*, hrs, aln, sec); 
ls_date (date) 


date; 




Int 

ath 

== (date»5) 

&0xf; 

Int 

day 

- (date) 

&0xlf; 

int 

yr = 

((date»9) 

&0x7f) + 80; 


printf(*X02d-X02d-X02d*. ath, day, yr); 
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5.9 NON-PRINTING ASCII CHARACTERS 


The following ASCII characters can be displayed on the 
screen, but will not appear in output to a printer: 


Hex 

Octal 

ASCII 

Hex 

80 

200 

% 

a2 

81 

201 


a3 

82 

202 

Sx 

a4 

83 

203 


as 

84 

204 


a6 

85 

205 


a7 

86 

206 


a8 

87 

207 


a9 

88 

210 

“s 

aa 

89 

211 

•V 

ab 

8a 

212 

S 

ac 

8b 

213 

''t 

ad 

8c 

214 

•“f 

ae 

8d 

215 


af 

8e 

216 


bO 

8f 

217 


b1 

90 

220 


b2 

91 

221 

“l 

b3 

92 

222 

“2 

b4 

93 

223 

“3 

bS 

94 

224 

°4 

b6 

95 

225 

“l 

b7 

96 

226 

Sy 

b8 

97 

227 


b9 

98 

230 


ba 

99 

231 


bb 

9a 

232 


be 

9b 

233 

"c 

bd 

9c 

234 

•“s 

be 

9d 

235 

«s 

bf 

9e 

236 

"s 

cO 

9f 

237 

“s 

cl 

aO 

240 

1 


al 

241 

t 



Octal 

ASCII 

Hex . 

Octal 

242 

□ 

C2 

302 

243 

Q 

C3 

303 

244 

X 

C4 

304 

245 

0 

C5 

305 

246 

Q 

c6 

306 

247 

0 

c7 

307 

250 

1 

c8 

310 

251 

*1 

c9 

311 

252 

1 

ca 

312 

253 

1 

cb 

313 

254 

1 

cc 

314 

255 


cd 

315 

256 


ce 

316 

257 

1 

cf 

317 

260 

4 

dO 

320 

261 


d1 

321 

262 

■■ 

d2 

322 

263 

- - 

d3 

323 

264 

r., 

d4 

324 

265 

1 

.d5 

325 

266 

r 

d6 

326 

267 

L 

d7 

327 

270 

J 

d8 

330 

271 

1 

d9 

331 

272 

T 

da 

332 

273 

1 

db 

333 

274 

\ 

dc 

334 

275 

/ 

dd 

335 

276 

• 

de 

336 

277 

/ 

df 

337 

300 

1 

eO 

340 

301 


el 

341 


ASCII 


III 

+ 


B 


T 

I 

1 

r 

j 

L 

+ 

T 

▲ 

I 



T 
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5.10 BERT LIBRARY FUNCTIONS 


This section presents the functions for Bit Error-Rate Testing 
supported by the Chameleon 32 C Development System compiler. 
These functions are defined in the file bertlib and are given here in 
alphabeitcal order within three, major functional categories (see the 
Section Table of Contents on the next page). These are: 

STARTUP AND IDLE MODE FUNCTIONS 

FUNCTIONS USED WHILE FEP IS RUNNING A TEST 

FUNCTIONS RELATED TO COLLECTING TEST DATA 


The section INTERVAL TESTING gives a sample program using 
some of these functions. 


GENERAL NOTES AND REQUIREMENTS 

As in other simulation libraries, before calling start_sync() or 
start_async(), the user program should call setport{). If this is not 
done, port selection will default to port A. 

User programs must be linked with the math library (libm.a) provided 
with system release 4.51 or later. Older versions may cause incorrect 
exponents to be displayed when the value is quite small. 

The include file (bertlib.h) must be included in the user program. 
Otherwise, the returns to user calls to library functions that return long 
or double values will be misinterpreted. 

This library uses a sub-task started by start_sync{) or start_async. 
This sub-task manages the collection of test data from the FEP, 
counts run-time seconds, errored seconds and timed tests. Because 
of this, there are three rules that must be observed when writing a user 
program: 

• Program loops must contain a ‘pauseQ’ call that will stop the 
program for a short time to allow the sub-task and any other tasks 
access to processor time. This means that ‘mtosux.h’ should be 
included in the user program. 

• While this library may be run on either port, testing on both ports 
requires running two separate programs. That is, you cannot start 
both ports from a single task, as the same sub task will be started 
twice and cause unpredictable results. 

• Terminate with an ‘exit(O)’ call to assure termination of the 
sub-^ask. 
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SECTION TABLE OF CONTENTS 

The 29 functions of the BERT Library fall into three categories: 

STARTUP AND IDLE MODE FUNCTIONS 5.10-3 

FUNCTIONS USED WHILE FEP IS RUNNING A TEST . 5.10-16 

FUNCTIONS RELATED TO COLLECTING TEST DATA . 5.10-23 

The functions in each category are listed one the first of the pages 
devoted to that category, as listed above. 
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STARTUP AND IDLE MODE FUNCTIONS 

blockjen 5.10-4 

drjpream 5.10-4 

cont_run 5.10-5 

one_block 5.10-5 

set_err_rate{sel) 5.10-6 

set_mode 5.10-7 

set _pream 5.10-7 

set_ptm 5.10-8 

start_async 5.10-9 

start_sync 5.10-10 

timed_test 5.10-10 

userjotm 5.10-11 
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BLOCK_LEN 

Declaration 

Description 


CLR__PREAM 

Declaration 

Description 


blockJen(b!len) 

Sets block length to be used in determining block errors, 
bllen = unsigned int, 64k max. 


dr _pream{) 

Stops using preamble. 


See SET PREAM. 
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CONT_RUN 

Declaration 

Description 


ONE_BLOCK 

Declaration 

Description 


cont_run() 

Sets FEP to active test mode. The test will continue to run until 
STOP_TEST( ) is called or the test program is terminated by a call to 
exit (0). 


one_block() 

Runs test for one block length, then returns to idle mode. 
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SET_ERR 

Deciiaration 

Description 


Returns 


RATE(SEL) 


set_err_rate(sei) 


Selects automatic error insertion rate. Only effective in SYNC testing. 


sel a 0, none 

1, 1.00E-5 

2. 1.00E-4 

3. 9,84E-4 

4. 1.00E-3 

5. 1.02E-3 

6. 1.04E-2 


0 - no probiems 
-1 - parameter error 


See ERROR^ON ( ), ERROR^OFF ( ), ONE_ERROR ( ) 
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SET_MODE 

Declaration 

Description 

Returns 


SET^PREAM 

Declaration 

Description 


set_mode(mode) 

Selects test mode, remote/local loopback, rx only. 


mode = 1 , Remote loopback 

2, local loopback 
4, receive only 


0 - no problems 
-1 - parameter error 


setjDream(ch1 ,ch2) 

Selects 2 byte user preamble to be transmitted at beginning of test 
run. 


ch1 s first byte to send 
ch2 « second byte to send 


See CLR_PREAM ( ) 
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SET_PTRN 

Declaration 

Description 


Returns 


set_ptrn(patsel) 


Selects the test pattern. For user defined pattern, partem location and 
length MUST be set using user _ptrn(). 


parsel = 0, bert 63 

1, bert511 

2, bert 2047 

3, bert 32767 

4, 10101010 

5, foxmes 

6, user defined 


0 - no problems 
“1 - parameter error 
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START_ASYNC 

Declaration 


Returns 


start_async(interface,dbits,sbits,parsel,rate) 


0. DCE 

1. DTE 


interface 


dbits = 


sbits » 


parsel » 


5.5 

6.6 

7.7 

8.8 


0,1 
1, 1.5 
2.2 


2, even 
1,odd 
0, none 


(Data bits) 


(Stop bits) 


(Parity) 


rate » 1 , 50 (Baud rate) 

2,75 
3, 110 

4, 150 

5, 300 

6, 600 

7, 1200 

8, 2400 

9, 4800 

10, 9600 
11, 19200 


0 - no problems 
-1 - parameter error 

(see also global error table in the C library manuai.) 
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START_SYHC 

Declaration 


Returns 

TIMED_TEST 

Declaration 

Description 


start_sync(interface,rate) 


interface = 0, DCE 

1, DTE 

2, ISDN 


rate = 50 - 64000 bps if DCE is selected, any if DTE is selected. 


0 - no problems 
-1 - parameter error 

(see also global error table in the C library manual.) 


timed_test(length) 

Run test for length seconds. 


length =» long int 

For the convenience of the user, multipliers have been added to 
bertiib.h to convert hours and minutes to seconds. 

EXAMPLE 

timed Jest(2*RN_HOURS + 1 0*RN_MINUTES + 30); will run a test 
for 2 hours 10 minutes and 30 seconds. 

NOTE 

This function sets up and starts the timed test, then returns. It will NOT 
tie up the user program for the duration of the test. All other library and 
user program functions will operate normally during a timed test. 


A call to stop_testO may be used to terminate a timed test before the 
selected length of time. 
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USER_PTRN 

Declaration 

Description 


Returns 


user_ptm(loc,len) 

Passes address and length of user defined pattern. *loc = pointer to 
user defined pattern len = length of pattern to send. Max length 4000 
bytes. 

*loc » pointer to user defined pattern 

len = length of pattern to send. Max length 4000 bytes. 

0 - no problems 
-1 - parameter error 
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FUNCTIONS USED WHILE FEP IS RUNNING A TEST 


error_off 
eiTor_on 
one_error 
resync . . 
status . . 
stopjest 


5 . 10-13 

5 . 10 - 13 

5 . 10 - 14 

5 . 10 - 14 

5 . 10 - 15 
5 . 10-15 
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ERROR_OFF 

Declaration 

Description 


ERROR_ON 

Declaration 

Description 


error_off() 

Stops automatic error insertion. 


See ERROR_ON ( ), ONE_ERROR ( ), SET_ERR_RATE 


error_on() 

Starts automatic error insertion. Requires previous call 
to’set_err_rate()’ to select error insertion interval. 


See ERROR_OFF ( ), ONE_ERROR ( ), SET_ERR_RATE 
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ONE_ERROR 

Declaration 

Description 


RESYNC 

Declaration 

Description 


one_error() 

Inserts one error in transmitted pattern independently of automatic 
error insertion. Ineffective if test is not running. 


See ERROR_ON ( ), ERROR_OFF ( ), SET_ERR_RATE ( ) 


resyncO 

Resynchronizes on data pattern. 


In the case of an excessively high error rate (25% or more) in one 
second, resynchronization will occur automatically. The errors for that 
second will be discarded and the sync loss counter will be 
incremented. This is because such a high error rate normaily means 
a loss of data, a data slip, or a change in received pattern has 
occurred. 


This function allows you to program a lower resynch threshold than 
that provided by the automatic resynch function. 
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STATUS 

Declaration 

Description 


STOP_TEST 

Declaration 

Description 


statusO 

Returns Sync status. 


0 = idle (test is not being run) 

1 = running, not in sync 

2 = running in sync 


stop_test() 

Stops test and return to idle mode. 


See CONT_RUN { ), ONE_BLOCK ( ), TIMED_TEST ( ) 
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FUNCTIONS RELATED TO COLLECTING TEST DATA 

double get_err_rate 5.10-17 

long get_bikerrs 5.10-17 

long get_errsec 5.10-18 

long get_rbits 5.10 -18 

long get_tbits 5.10-19 

long get„rbiterrs 5.10-19 

long get_runtime 5.10-20 

long get_serrsec 5.10-20 

long get_syncloss 5.10-21 

long get_tbiterrs 5.10-21 

reset data 5.10-22 
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DOUBLE GET_ERR_RATE 

Declaration double get_err_rate{) 

Description Returns cumulative bit error rate in floating point format. 

To display the result, use the format code 2.2le. 
EXAMPLE: 

printf(The error rate is %2.2le\n”,get_err_rate()); 


LONG GET_BLKERRS 

Declaration long get_blkerrs() 

Description Returns the number of received block errors. (See blockJen()) 
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LONG GET 

Oeciaration 

Description 


LONG GET 

Declaration 

Description 


ERRSEC 

long get_errsec{) 

Returns the number of seconds during which one or more bit errors 
were received. 


RBITS 

long get_rbits() 

Returns the number of received bits. 
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LONG GET 

Declaration 

Description 


LONG GET 

Declaration 

Description 


TBITS 

long get_tbits() 

Returns the number of transmitted bits. 


RBITERRS 

long get_rbiterrs() 

Returns the nunber of received bit errors. 
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LONG GET 

Declaratiion 

Description 


LONG GET 

Declaration 

Description 


RUNTIME . 

long get._runtime{) 

Returns the cumulative number of seconds during which the library is 
in active test mode. For example, this function will return 7’ when: 

• cont_run() is called 

• 5 seconds later stopJtesiQ is called 

• then, the test is restarted 1 0 seconds later and again stopped after 
2 seconds 


SERRSEC 

long get_serrsec() 

Returns the number of seconds during which the received bit error 
rate was 1 0E--3 or greater. 
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LONG GET 

Oeciaration 

Description 


LONG GET 

Oeciaration 

Description 


SYNCLOSS 

long get_syncloss{) 

Returns the number of times that the received error rate was so high 
that an automatic resync occured. 

The returned value does not include calls to RESYNC( ) by the user 
program. 


TBITERRS 

long get_tbiterrs() 

Returns the number of transmitted bit errors when auto error insertion 
is on. 
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RESET_DATA 

Declaration reset_data() 

Description Resets the counters for all the above to zero. 
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TIMED TEST EXAMPLE 


The following program fragment is suggested as a means of running 
a BERT test for a selected time interval. At this point, the FEP should 
have been started using start_sync{) or start_async{) and the 
parameters (e.g., mode, pattern, block length, etc.) set. 

printf(”\033[2J”); /* Clear screen V 

timed_test(5 * RN_M1NUTES); /* Start 5 minute timed test 7 

while(status()){ /* as long as test is running 7 

printf(”\033[1;ir); /* position cursor at 1,1 7 

printffRun time %01 0.0l[iseconds\n” 

get_runtime{); /* %01 0.Olu prints in fixed 1 0 place format 7 

/* print all other test results of interest 7 

pause(1 + HMS);7* wait 100 msec so other tasks can use 
processor 7 

} /* end of while loop 7 

/* Using ’HMS’ or other mnemonic in pause() requires inclusion of 
MTOSUX.h 7 


ADVANCED PROGRAMMING TECHNIQUE: 

GETTING CORRECT RESULTS FROM VERY LONG TEST RUNS 


A structure of long integers is used to store the collected test data. A 
long, as defined by the Tekelec C compiler, will overflow at a value 
slightly above two billion. To avoid problems during long test runs, 
bertlib.h provides the user with a pointer to the data structure so that 
individual values can be reset and an extension counter incremented. 
An example of this is in the following program fragment " 

unsigned int tbit_oflo = 0; 

if(getjbits() >- 1000000000L){ 

tes_data->tx_blts — 1 0OOOOOOOOL; /‘adjust the count7 
tbitjoflo ++; /* and incr the extension counter 7 
} 

It is important that rx_bterrs should be reset any time rx_bits 
is cleared to avoid incorrect bit error rate calculation by the 
get_err_rate() function. 
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6.1 USING THE Vi EDITOR 


The Chameleon 32 C package provides an editor, called vi, 
which is similar in function to versions of the vi editor 
commonly in use. 

If you are familiar with vi, you may not need to read this 
section in detail. The last few pages of the section contain a 
listing of all commands and their definitions. A vi quick 
reference chart is also included in the Chameleon 32 Quick 
Reference Guide. 

if you are unfamiliar with vi, you may want to create a text file 
to practice using the vi commands as you read this chapter. 


Special Keys Esc, Return, and Delete have the following functions in vi: 

Esc The Esc key cancels incomplete commands. Press 
Esc if you have typed an incorrect command, or if 
you are not sure what commands you have already 
typed. Esc also exits from vi insert mode. 

Return The Return key terminates commands. 

Delete When inserting a command line. Delete moves the 
cursor one character to the left. When you then 
press Esc or Return, the characters to the right of 
the cursor are erased. 


Entering vi To edit a file in the C Shell page, type the command: 

vi filename 

If the file exists, the file is displayed in the C Shell page. If the 
file does not exist, vi will assume you are creating a new file. 

To edit a file in a separate page, use the syntax: 

vi filename & 
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Exiting vi 


Text Display 


This displays the file for editing in a VI page, which is separate 
from the C Shell page. Likewise, if the file does not currently 
exist, vi assumes it is a new file you wish to create. 

The tags ( -t) option invokes the vi editor to edit one or more 
files which contain a specified function (tag). For example, the 
following command invokes the vi editor to edit the files that 
contain the function specified by tagname, and positions the 
cursor at the first occurrence of the function: 

vi -t tagname 

In order to use the -t option, you must have used the shell 
ctags command, which creates a tags file containing 
information about the functions in the target files. Refer to the 
ctags command in Section 2.1 for more information. 

Also refer to the .tag command on page 6.1-3 which enables 
you to search for tags once you are in vi. 


To exit vi, use the following commands: 

22 Exits vi and saves the changes made to the file. 

:q Exits vi without saving the changes made to the file. 

Only use this commsuid if you are sure you want to 
discard the changes made to the hie. 


The commands below move the text within the page. 


CTRL B 

Moves backward one page. 

CTRLD 

Moves half a page forward. 

CTRL E 

Moves the page down one line, leaving the 
cursor at its current location. 

CTRL F 

Moves forward one page. 

CTRL U 

Moves half a page backward. 

CTRL Y 

Moves the page up one line, leaving the cursor 
at its current location. 

z. 

Causes current line to be displayed in the 
center of the page. 

z- 

Z < Return > 

Causes current line to be displayed at the top 
of the page. 
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Search 

Commands You can also move through the file by searching for a string, 

using the following command: 

/xxxxxxx < Return > 

where xxxxxxx is any character string. If the string is not 
present in the file, the editor indicates that this is the case, and 
returns the cursor to its original position. Additional search 
commands are: 

n Searches forward for the next occurrence of the string 

? xxxxxxx < Return > Searches backward through the file for 

the character string xxxxxxx. 

/‘xxxxxxx A caret at the beginning of the character string 
searches for strings at the beginning of a line. 

/xxxxxxx$ A dollar sign at the end of the character string 
searches for strings at the end of a line. 

.tag tagname Positions the cursor at the first occurrence of 
the function specified by tagname in the files 
being edited. 

In order to use tag, you must have used the 
shell ctags command, which creates a tags 
file containing information about the functions 
in the target files. Refer to the ctags 
command in Section 2.1 for more information. 


Positioning 

Commands You can move through the file by specifying a line number 

using these commands: 

xG Moves the cursor to line x. 

G Moves the cursor to the end of the file. 

Ctrl G Display information about the file, including: 

-the line number the cursor is positioned on 
-the name of the file you are editing 
-the number of lines in the buffer 
-the percentage of the way through the buffer 

"" Two back quotes moves you back to a previous 

position 
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Screen Movement 
Commands 


Line Movement 


The four arrow keys (-> i •«- 1 ) move the cursor to any position 

on the screen. Other cursor commands include; 

+ Moves to the first non-white character on the next 

line 

n + Moves to the first non-white character down n lines 

from the current line 

- or 

k Moves up one line. 

n- or 

nk Moves to the first non-white character up n lines 

from the current line 


Once you reach the line you want, you can move the cursor 
within the line using the following commands: 


b 

Moves 

nb 

Moves 

e 

Moves 

ne 

Moves 

backspace or 

h 

Moves 

nh 

Moves 

spacebar or 

1 

Moves 

ni 

Moves 

w 

Moves 

nw 

Moves 
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Insert Mode 


Note that the w and b commands treat punctuation as words, 
and therefore stop the cursor at punctuation marks. The 
corresponding upper case commands do not treat punctuation 
as words: 

B Moves to the beginning of the preceding word. 

nB Moves back n words. 

W Moves to the beginning of the next word. 

nW Moves forward n words. 


When you first enter the vi editor you are in command mode. 
The command mode enables you to move the cursor around 
in the file. If you want to add, change, and/or delete text, you 
must change to Insert mode. To enter insert mode, type: 

I 

In insert mode, the keys that you press are interpreted as text 
Input, and are entered to the left of the cursor. 

There is also an append mode, which causes typed 
characters to be entered to the right of the cursor. To enter 
append mode (from command mode), type: 

a 

To exit either the insert mode or the append mode, and return 
to command mode, press Esc. 

If you want to insert a new line between existing lines of text, 
use the following commands: 

0 Creates a new line below the current line, and enters 
insert mode. 

0 Creates a new line above the current line and enters 
insert mode. 

While in either the O or o mode, press Return to insert 
additional new lines of text. To exit o or 0 mode, press Esc. 

You can also enter position the cursor and enter insert mode 
using the following commands: 

A Move to the end of the line and enter insert mode 

1 Move to the beginning of the line and enter insert mode 
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Deleting 

Characters 


Delete Command 


To make a correction when you are in command mode, use 
the positioning keys described previously to place the cursor 
over the character to be corrected, enter insert mode, and 
then use one of the following commands: 

X Deletes the character directly under the cursor 

X Deletes the character left of the cursor 

nx Deletes n characters beginning with the character directly 
under the cursor. 

rx Deletes the current character and replaces it with 
character x. 

sbbbb Esc Deletes the current character and replaces it 
with the string bbbb. 

nsbbbb Esc Deletes n characters beginning with the 
character directly under the cursor, and 
replaces them with the character string bbbb. 


Some commands are used with other commands to augment 
their functions. For example, the d (delete) command can be 
used in conjunction with other commands to delete different 
amounts of text. For example: 

db Deletes the word preceding the cursor 

dd Deletes the current line 

ndd Deletes n lines 

dL Deletes all lines up to and including the last line on 

the screen 

dnL Deletes all lines up to the nth line from the bottom 
of the screen. 

dw Deletes a word 

ndw Deletes n words 
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Change Command 


Undoing 

Changes 


Moving Around 
Quickly in a File 


The c (change) command can be used as follows: 
cwxxxxEsc Changes the text of a word to text xxxx 
ccxxxx Esc Changes the current line to text xxxx 


The following ocmmand are available for undoing (reversing) 
the effect of the preceding commmand: 

u Undoes the last command, as if the command were 

never performed 

uu Undoes the undo command, replacing the change 

which was undone by the u command 

U Undoes the last command (up to 9 commands) 


One way to move quickly to a certain place on a line is to use 
a search command to search for a punctuation mark, and a 
repeat command command to move to successive 
occurrences of the punctuation mark. 

To do this use the following commands: 

fx Move to the next occurrence of character x on the 

current line 

; Moves to the next instance of the same character. 

To work with characters up to but not including character x, 
you can use the t (up to) command. For example: 

dtx Deletes characters up to but not including the 
character x. 

To move to the first non-white position on the current line, use 
the command: 


To move to the begining of the previous line, use the 
command: 
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Tab 

Characters 


REARRANGING 

TEXT 


To move to the end of a line, use the command: 

S 

For example, the command Sa allows you to add new text to 
the end of a line. 


Tab and non-printing characters are treated as if they are a 
single character, even though they take up move than one 
character space in a file. Tabs are represented by CTRL I. 
When the cursor moves to a tab or non-printing character, it 
rests on the last space that represents the tab or character. 

If you space or backspace over a non-printing character 
(represented by a CTRL character and another character), the 
cursor moves over it as if it were a single character. 

The vi editor ignores the CTRL character if you insert it into a 
file. If you want to be sure the vi editor does not ignore the 
character, you must type a CTRL V before the CTRL 
character. 


The w editor provides a number of text buffers. There is an 
unnamed buffer which the editor uses to save the last deleted 
or changed text, and a set of 26 buffers named a through z 
which you can use to save copies of text, to move text around 
in your file, and to move text between files. 

You can use the command: 


to put selected text into a buffer, where x specifies the buffer 
name (a-z). If there is no buffer specified, the text will be put 
into the unnamed buffer. To put the contents of a buffer back 
into a file, use these commands: 

p Puts the text after or below the cursor 

P Puts the text before or above the cursor 

If the text you put in the buffer started with a line that was not 
an entire line, it will be put back directly next to the cursor. If 
the text you put in the buffer formed complete lines, it will be 
put back as complete lines. 
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yp Makes a copy of the current line and positions the 

cursor on the copy. 

nVP Makes a copy of n lines and positions the cursor on 
the copy. 

Yp Makes a copy of the current line, and positions the 

cursor after the current line. 

nYp Makes a copy of n lines, and positions the cursor 
after the current line. 

To move text from one place in a file to another place in a file, 
use a delete (d) command to move the text into a buffer and a 
put (p) command to move the text from the buffer into the new 
location in the file). For example, to move six lines of text, use 
the following command sequence: 

“a6dd Deletes six lines and puts the deleted text into 
buffer a 

Move the cursor to the new location for the text 

ap Puts the text in buffer a following the current 

position of the cursor. 


Marking Your 

Place You can return to the previous cursor position using the 

command “. You can also mark places in your file with single 
letter labels, then return to these labels later by specifying the 
label name. The mark commands are: 

mx The cursor position is marked with the reference x, 

which is a letter from a - z. 

’x Returns the cursor to the poitiosn marked with the 

reference x. 

*x Moves to the beginning of the line in which the 

mark is located 

Note that the labels disappear when you edit another file. 
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Adjusting the 

Screen The following commands move lines and formfeeds: 

Ctrl L This is the formfeed character, and causes the 
screen to be repainted. 

2 Moves the current line to the top of the screen 

2. Moves the current line to the center of the screen 

2- Moves the current line to the bottom of the screen. 


Switching 

Between Files You can edit a different file without leaving the vi editor by 

entering the command: 

:e ff/ename < Return > 

If you enter the command and you have not yet saved your 
editing changes, the editor will remind you to do this first. You 
can use the command :w < Return > to to save the file. Then, 
give the :e filename < Return > command again. Or, you can 
use the command: 

:e! filename < Return > 

which causes ail the changes you made to the existing file to 
be discarded, and opens up the specified new file for editing. 
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Editor Options Editor options are shown in the table below. 


Name 

Command 

Default 

Description 

autoindent 

ai 

noai 

Automatic indentation on/off 

autowrite 

aw 

noaw 

Automatic write before :n, :ta, CTRL', ! on/off 

ignorecase 

ic 

noic 

Ignore case in searching on/off 

list 

list 

nolist 

Tabs print as CTRL 1; end of lines marked with S 
on/off 

magic 

magic 

magic 

The characters .[ and * are special in scans on/off 

shiftwidth 

sw = n 

II 

00 

Shift n characters for < , > and input CTRL D and 
CTRLT 

tabstop 

ts = n 

ts=4 

Sets n number of characters indented for tab 

wrapscan 

ws 

WS 

Wrapscan on/off 


You can put these statements in your EXIN IT, or give the 
commands while running vi. While in vi, you must precede the 
comments with a colon (:) and end them with Return. There 
are two kinds of options: 

numeric options 
on/off toggle options 

You can set numeric options by a statement of the form: 
set option - value 

For example, in vi, the following sets the tabstop to 5: 

:set ts = 5 

You can change toggle options on or off, using the form: 

set option 
set noopUon 

For example. In vi to turn autoindent on, use the command: 

:set ai 

To turn autoindent off in vi, use the command: 

:set noai 
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To display a list of set options and their current settings, use 
the command: 

:set all < Return > 

set can be abbreviated se. Multiple options can be placed on 
one line, for example: 

:se ai aw < Return > 

Options set by the set comand only last while you are in the vi 
editor. If you want to have certain options set whenever you 
use the vi editor, you can create a list of commands to set up 
those options. The command list will be run every time you 
open up the editor. 

The following example sets the autoindent and autowrite 
options, makes the @ character function as a “delete line” 
key; and makes the # character function as a “delete a 
character” key. 

set ai aw|map @ dd|map # x’ 

Redefining characters is described later in this chapter. 

The command string should be put in the variable EXINIT. If 
you use csh, put this line in the file .login in your home 
directory. 


Recovering 

Deieted Text The vi editor saves the last nine deleted blocks of text in a set 

of registers numbered 1-9. To get the nth previous deleted 
text back into your file, use the command: 

”np 

where n is the number of the buffer you need. If you want to 
see the buffer after the nth buffer, use the command: 


The period command, in general, causes the last command 
typed to be repeated. For the ”np command, however, it 
increments the buffer number before it re-executes the 
command. 
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If you are inputting large amounts of text, and you want to 
avoid pressing Return at the end of every line, use the 
command: 

wm=:10 < Return > 

This command causes each line to be broken at a space of at 
least 10 columns from the right margin. To put a broken line 
back together, use the command: 

J 

If you need to put several lines together, you can precede the 
J with the number of lines. For example, 4J joins 4 lines 
together. 


The vi editor provides a number of high level editing functions 
such as automatic tab indention and parenthesis matching. 
These functions are described below. 

The command: 

:seai < Return > 

sets autoindent mode. While in this mode, all lines typed after 
a tab will automatically line up under that tab. You will not be 
able to backspace over the automatically inserted tabs, but 
you can use the Ctrl D command to backtab over the tabs. 
For every the cursor will back up one tab position, usually 8 
spaces. You can use the command: 

:sesw=x < Return > 

to change the number of spaces represented by one tab 
position. X represents the number of spaces, sw is called the 
shiftwidth function. 


You can shift lines in your file to the right and to the left by 
using the command: 

>> 

to shift your line one shiftwidth to the right, and 
<< 

to shift your line one shiftwidth to the left. 
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Matching 

Parentheses 


Macros 


If you want to track how parentheses are matched in a 
complex expression, you can move the cursor to the right or 
left parenthesis and use the command: 


% 

This will show you the matching parenthesis. The command 
can also be used for { } and [ ]. 


The vi editor allows you to create macros. Macros are user- 
specified combinations of keystrokes set up to execute at a 
single keystroke command. There are two types of macros: . 

1. You can put the macro In a buffer register, for example, 
Register x. You will then be able to type @x to run the 
macro. You can also type @@ to repeat the last macro. 

2. You can use the map command from vi as follows: 

:map x y 

where x is the name of the macro, and y is the listing of 
commands. Note that: 

X should be one keystroke because, it must be 
entered within one second (unless notimeout is 
set). 

X can be no more than 10 characters 

y can be no longer than 100 characters 

To put a space, tab, or newline into x or y, you 
need to escape them with a Ctrl V. 

Spaces and tabs inside y need not be escaped. 

To delete a macro, use the command: 

unmap x 


If the macro x is #0 through #9, this maps the particular 
function key instead of the 2 character sequence of the pound 
sign and the number. 

You can place a ! after the word map to cause the mapping to 
apply to input mode. Instead of command mode. 
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Word 

Abbreviation 


Lines and the 
vi Editor 


There is a word abbreviation function similar to the macro 
function which allows you to type an abbreviation that the 
editor will automatically spell out. Use the command: 

:abxxxyyyyyyyyyyyyyyyy yyyyy 

where xxx is the abbreviation and yyyyyyyyyy yyyyyy yyyyy is 
the expanded version of the abbreviation. Only whole words 
are affected. If xxx is part of a larger word, the vi editor will 
not change it. xxx does not need to be limited to a single 
keystroke. 


The editor folds long logical lines onto many physical lines in 
the display. Line commands affect logical lines. The vi editor 
puts only full lines on the display. If there is not enough room 
for an entire logical line, the vi editor will not put part of the 
line on the screen, but will leave it empty and use a @ as a 
place holder. 

You can cause tabs to be represented as Ctrl I and the ends 
of lines represented by S by using the command :se list 
< Return > to enable, and :senolist < Return > to disable. 

When the file ends above the last line on the screen, the 
missing lines are represented by the character 
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Counts 


As stated previously, many w commands use a number 
preceding ttie command to alter the command. For example: 


new window size 
scroll amount 
line/column number 
repeat 


: / ? * 

CTRLD CTRLU 
z G 

most of the rest 


The vi editor remembers the current default window size. This 
is the size used when the vi editor clears and refills the screen 
after a search or repositions the cursor far from the current 
window. 


The scroll commands CTRL D and CTRL U remember the 
amount of scroll last specified, starting with one half the 
window size. 

ExOept for a few commands, the rest of the editor commands 
use a count to indicate a simple repetition of their effect. For 
example, 6w advances six words on the current line. 


File Manipulation 

Commands The following table lists the file manipulation commands. 


Command 

Description 

:w 

Write back changes 

:wq 

Write and quit 

:x 

Write Of necessary) and quit (same as ZZ) 

:e name 

Edit file name 

:ei 

Re-edit, discarding changes 

:e*name 

Edit, starting at end 

:e + n 

Edit, starting at line n 

:e# 

Edit alternate file 

:w name 

Write file name 

nwl name 

Overwrite file name 

:x,yw name 

Write lines x through y to name 

:r name 

Read 6ie name into buffer 

:n 

Edit next file in argument list 

:nl 

Edit next file, discarding changes to current 

:n args 

Specify new argument list 
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SEARCHING FOR 
STRINGS 


Magic 


As the list indicates, if you make changes to the editor copy of 
the file, but do not want to write them back, then you must 
give an ! after the command you are using. 

The :e command can be given a + argument to start at the 
end of the file, or a + n argument to start at line n. 

The % character replaces the current filename, and the # 
character replaces the alternate filename. 

You can write part of the buffer to a file by finding out the lines 
that bound the range to be written using the Ctrl G command, 
and giving these numbers after the : and before the w, 
separated by /s. You can read another file into the buffer 
after the current line by using the :r command. You can also 
read in the output from a command by using !cmd instead of a 
file name. 

To edit a number of files in succession, you can give all the 
names on the command line, and then edit them in turn by 
using the command :ii. 


When you search for strings using / and ?, the editor normally 
places you at the next or previous occurrences of the string. 
If you want to affect lines up to the line before the line 
containing the string, you can use a command of the form: 

Ipatl-n 

to refer to the nth line before the next line containing pat, or 
you can use + instead of - to refer to the lines after the one 
containing pat If you do not give a line offset, the vi editor 
affects characters up to the pat, rather than whole lines; thus 
use +0 to affect to the line which matches. 

To have the vi editor ignore the case of the words in the 
search, use the command: 

:se ic < Return > . 

The command :senoic < Return > disables this. 

Strings searched for may contain regular expressions. If you 
do not need this, you can give the command: 

set no magic 

in your EXINIT. Then, only the characters * and S are special. 
The character \ may be used for an extended pattern matching 
facility. It is necessary to use a \ before a / In a forward 
search, or a ? in a backward search. 
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The table below shows extended forms when magic is set. 


Command 

Description 

* 

At beginning of pattern, matches beginning of line 

S 

At end of pattern, matches end of line 

. 

Matches any character 

\< 

Matches the beginning of a word 

\> 

Matches the end of a word 

[str] 

Matches any single character in str 

Vstr] 

Matches any si ngl e character not i n str 

[x-y] 

Matches any character between x and y 

* 

Matches any number of the preceding pattern 


If you are using nomagic, the . [ and * primitives are given 
with a preceding \. 


Correction 

Characters There are a number of characters which you can use to make 

corrections during input mode. These are shown in the 
following table. Your system kill character CTRL X or 
CTRL U) will erase all the input you have given on the current 
line. If you want to type in your erase or kill character, you 
must precede it with a \. 


Command 

Description 

CTRLH 

Deletes the last input character 

CTRLW 

Deletes the last input character, defined as by b 

erase 

Your erase character, same as CTRL H 

kill 

Your kill character, deletes the input on this line 

\ 

Escapes a following ctrlh and your erase and kill 

ESC 

Ends an insertion 

DEL 

Interrupts an insertion, terminating it abnormally 

CR 

Starts a new line 

CTRLD 

Backtabs over autoindent 

OCTRLD 

Kills ail the autoindent 

CTRLD 

Same as o Ctrl d, but restores indent next line 

CTRLV 

Quotes the next non-printing character into the file 
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vi Softkeys 
Introduction 


Softkey 

Options 


There are several softkeys that correspond to vi commands 
that you can use to edit your programs. The softkeys act as 
macros. When you press the softkey, the command is typed 
onto the screen. You must then type any additional 
information (filename, for example), that is required by the 
syntax, and then press Return to execute it. 


There are two sets of vi softkeys. When you load the vi editor, 
the first softkey strip appears at the bottom of the Chameleon 
32 screen, as follows: 


Open 

Save 

Quit 

Sav/Qit 

Revert 

Read 

Set 

Next 

Rewind 

EDIT 

F1 

F2 

F3 

F4 

F5 

F6 

F7 

F8 

F9 

F10 


These are the FILE softkeys. In general, the FILE softkeys 
enable you to select a file for editing, save files, set editor 
options, and exit from vi. 

When you press F10 Edit the second set of vi softkeys, the 
EDIT softkeys, are active, as shown below: 


insert 

Append 

Del chr 

Cut 

Copy 

Paste 

Srch Fw 

Srch Bk 

Again 

FILE 

FI 

F2 

F3 

F4 

F5 

F6 

F7 

F8 

F9 

F10 


In general, the EDIT sofkeys enable you to make changes to 
the text in your program file. If you select F1 Insert or F2 
Append the softkey strip disappears from the screen because 
the other options are invalid when you are in either of these 
modes. To escape from the Insert or Append mode and 
redisplay the softkey strip, press the Esc key. 

Use the F10 key to move between the EDIT and FILE softkey 
strips. 

Table 6.1-1 lists the softkeys, a brief description of the 
commands they represent, and a page reference for more 
information about the command syntax and usage. 
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Softkey Strip 


FILE 

SOFTKEYS 


Softkey 


F1 - Open 


F2 - Save 


F3 - Quit 


F4 - Sav/Qit 


F5 - Revert 


F6 - Read 


F7 - Set 


F8 - Next 


F9 - Rewind 



Description 


Edit file 



Save changes 


Quit vi and return to % 


Save changes and quit vi 


Discard changes made to current 
file and re-edit 


Read file into buffer 


Set editor options 


Edit next file in argument list 


Edit previous file in argument list 


See 

Page 


6.1-16 



6.1-16 


EDIT 

SOFTKEYS 


FI - insert 


F2 - Append 


F3 - Del chr 


F4 - Cut 


F5 - Copy 


F6 - Paste 


F7 - Srch Fw 


F8 - Srch Bk 


F9 - Again 






Insert before cursor 


Append after cursor . 


Delete a character 


Put line into buffer 


Make a copy of the current line 
below the cursor 


Copy line from buffer below 
cursor 


Search forward from cursor for 
specified string 


Search backward from cursor for 
specified string 


Redo last operation 






Table 6.1-1: vi Softkey Assignments 
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vi On-Line Help 


When you are in the vi editor, you can access on-line help by 
pressing the Help key on the Chameleon 32 keyboard. It is 
located to the right of the space bar. 

To exit from the on-line help, and return to the vi editor, press 
any key. 
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6.2 COMMAND REFERENCE 


The following tables list each vi command and give detailed 
definitions. Control characters are listed first, then special 
characters, then digits, and finally, upper and lower case. 


A brief Quick Reference Guide is included in the Quick 
Reference section of this manual. 
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CONTROL CHARACTERS 


Command 

Definition 

CTRL A 

Density 

CTRLB 

Move a full window backward. A count specifies repetition. Two lines 
of continuity are kept if possible. 

CTRLC 

Not used 

CTRLD 

As a command, scrolls down a half-window of text. A count gives the 
number of logical lines to scroll, and is remembered for future CTRL 

D and CTRL U commands. During an insert, backtabs over 
autoindent white space at the beginning of a line; this white space 
cannot be backspaced over. 

CTRLE 

Move the window down one line. 

CTRLF 

Move a full window forward. A count specifies repetition. Two lines 
of continuity are kept if possible. 

CTRLG 

Equivalent to :f CR, printing the current file, whether it has been 
modified, the current line number and the number of lines in the file, 
and the percentage of the way through the file that you are. 

CTRL H (BS) 

Move left one character (same as left arrow or h). During an insert, 
eliminates the last input character, backing over it but not erasing it; it 
remains so you can see what you typed if you wish to type something 
only slightly different 

CTRL 1 (TAB) 

Not a command character. When inserted, it prints as some number 
of spaces. When the cursor is at a tab character, it rests at the last 
of the spaces which represent the tab. The spacing of tab stops is 
controlled by the tabstop option. 

CTRL J (LF) 

Same as down arrow. 

CTRLK 

Move up one line (sme as k). 

CTRLL 

Move right one character (same as 1) 

CTRLM 

Move to the first non-white character on the next line. 

CTRLO 

Not used 

CTRLQ 

Not a command character. In input mode, CTRL Q quotes the next 
character 

CTRLR 

Redraws the current screen, eliminating logical lines not 
corresponding to physical lines (lines with only a single @ character 
on them). 

CTRLS 

Unused 

CTRLU 

Moves half a window forward: 
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CONTROL CHARACTERS 


Command 

Definition 

CTRL V 

Not a command character. In input mode, quotes the next character 
so that it is possible to insert non-printing and special characters into 
the file 

CTRL W 

In insert mode, deletes the last word typed. 

CTRLX 

Not used 

CTRL Y 

Moves the window up one line. 

CTRLZ 

Not used 

CTRL\ 

Not used 

CTRL ] 

Searches for the word which is after the cursor as a tag. Equivalent 
to typing :ta, this word, and then a CR. . 

CTRL ‘ 

Equivalent to :e # CR, returning to the previous position in the last 
edited file, or editing a file which you specified if you got a “No write 
since last change diagnostic" and do not want to have to type the file 
name again. 

CTRL_ 

Not used 
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SPECIAL CHARACTERS 


Command 










Same as right arrow 


Precedes a named buffer specification. There are named buffers 1 - 
9 used for saving deleted text and named buffers a*z into which you 
can place text. 


Moves to the end of the current line. If you :se list CR, then the end 
of each line will be shown by printing a $ after the end of the 
displayed text in the line. Given a count, advances to the count 
following the end of line. 


Moves to the parenthesis or brace which balances the parenthesis or 
brace at the current cursor position. 


When followed by a ’ returns to the previous context at the beginning 
of a line. The previous context is set whenever the current line is 
moved in a non-relative way. When followed by a letter a-z, 
returns to the line which was marked with this letter with an m 
command, at the first non-white character in the line. When used 
with an operator such as d, the operation takes place over complete 
lines; if you use the operation takes place from the exact marked 
place to the current cursor position within the line. 


Not used 


Same as CR when used as a command 


Repeats the last command which changed the buffer. Especially 
useful when deleting words or lines; you can delete some words/lines 
and then hit. to delete more and more words/lines. Given a count, it 
passes it on to the command being repeated. 


A macro character. If this is your fill character, you must escape it 
with a \ to type it in during input mode, as it normally backs over the 
input you have given on the current line. 


An operator which shifts lines right one shiftwidth, normally 8 spaces. 
Like alt operators, affects lines when repeated, as in > > . Counts 
are passed through to the basic object. 
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SPECIAL CHARACTERS 


Command 




Reads a string from the last line on the screen, and scans forward for 
the next occurrence of this string. The normal input editing 
sequences may be used during the input on the bottom line. The 
search begins when you hit CR to terminate the pattern; the cursors 
moves to the beginning of the last line to indicate that the search is in 
progress; the search may then be terminated with a DEL or RUB, or 
by backspacing when at the beginning of the bottom line, returning 
the cursor to its initial position. Searches normally wrap end-around 
to find a string anywhere in the buffer. 

When used with an operator, the enclosed region is normally 
affected. By mentioning an offset from the line matched by the 
pattern you can force whole lines to be affected. To do this give a 
pattern with a closing / and then an offset + n or -n. 

To include the character / in the search string, you must escape it 
with a preceding \. A * at the beginning of the pattern forces the 
match to occur at the beginning of a line only; this speeds the 
search. A $ at the end of the pattern forces the match to occur at 
the end of a line only. More extended pattern matching is available. 


Used for numeric arguments to commands 


A prefix to a set of commands for file and option manipulation and 
escapes to the system. Input is given on the bottom line and 
terminated with an CR, and the command then executed. You can 
return to where you were by hitting the DEL or RUB if you hit : 
accidentally. 


Repeats the last single character find which used f F t or T. A 
count iterates the basic scan. 


An operator which shifts lines left one shiftwidth, normally 8 spaces. 
Like all operators, affects lines when repeated, as in < < . Counts 
are passed through to the basic object. 


Scans backwards, the opposite of /. 
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UPPER CASE COMMANDS 


Command 


Description 










Append at the end of the line 


Backs up a word, where words are composed of non-blank 
sequences, placing the cursor at the beginning of the word. A count 
repeats the effect. 


Changes the rest of the text on the current line; same as c$ 


Deletes the rest of the text on the current line; same as d$ 


Moves forward to the end of a word, defined as blanks and non- 
blanks, like B and W. A count repeats the effect. 


Goes to the line number given as the preceding argument, or the end 
of the file if no preceding count is given. The screen is redrawn with 
the new current line in the center if necessary. 


Move to the first line in the window (home position). 


Inserts at the beginning of a line; same as ‘i. 


Joins together lines, supplying appropriate white space; one space 
between words, two spaces after a ., and no spaces at all if the first 
character of the joined on line is a ). A count causes n lines to be 
joined. 


Not used 


Move to the last line in the window or to the nth line above the last 
line in the window. 


Scans for the next match of the last pattern given to / or ?, but in the 
reverse direction; this is the opposite of n. 


Opens a new line above the current line and inputs text there up to 
an ESC. 


Puts the last deleted text back before/above the cursor. The text 
goes back as whole lines above the cursor if it was deleted as whole 
lines. Otherwise, the text is inserted between the characters before 
and at the cursor. May be preceded by a named buffer specification 
”x to retrieve the contents of the buffer; buffers 1-9 contain deleted 
material, buffers a-z are available for general use. 


Not used 


Enter replace mode. Terminates with an ESC. 
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UPPER CASE COMMANDS 
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LOWER CASE COMMANDS 


Command 


Description 









Appends arbitrary text after the current cursor position; the insert can 
continue onto multiple lines by using CR within ^e insert. A count 
causes the inserted text to be copies, but only if the inserted text is 
ail on one line. The insertion terminates with an ESC. 


Backs up to the beginning of a word in the current line. A word is a 
sequence of aiphanumerics, or a sequence of special characters. A 
count repeats the effect. 


Deletes the specified text and enters insert mode. 


Deletes the specified text. 


Advances to the end of the next word, defined as for b and w. A 
count repeats the effect. 


Finds the first instance of the next character following the cursor on 
the current line. A count repeats the find. 


Not used 


Left arrow. Moves the cursor one character to the left. Like the 
other arrow keys, either h, the left arrow key, or one of the synonyms 
(*H) has the same effect. A count repeats the effect. 


Inserts text before the cursor, otherwise like a 


Down arrow. Moves the cursor one line down in the same column 


Up arrow. Moves the cursor one line up. *P is a synonym. 


Right arrow. Moves the cursor one character to the right. SPACE is 
a synonym. 


Marks the current position of the cursor in the mark register which is 
specified by the next character a*z. Return to this position or use 
with an operator using ’ or ‘. 


Repeats the last / or ? scanning commands. 


Opens new lines below the current line; otherwise tike O. 


Puts text from the unnamed buffer following the cursor. 


Not used. 
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LOWER CASE COMMANDS 


Command 









Description 


Replaces the single character at the cursor with a single character 
you type. The new character may be a CR; this is the easiest way to 
split lines. A count replaces each of the following count characters 
with the single character given. R is usually more useful than r. 


Changes the single character under the cursor to the text which 
follows up to an ESC; given a count, that many characters from the 
current line are changed. The last character to be changed is 
marked with $. 


Advances the cursor up to the character before the next character 
typed. Most useful with operators such as d and c to delete the 
characters up to a following character. You can use . to delete more 
if this doesn’t delete enough the first time. 


Undoes the last change made to the current buffer. If repeated, will 
alternate between these two states, thus is its own inverse. When 
used after an insert which inserted text on more than one line, the 
lines are saved in the numeric named buffers. 


Not used 


Advances to the beginning of the next word. 


Deletes the single character under the cursor. With a' count deletes 
that many characters forward from the cursor position, but only on 
the current line. 


An operator, yanks the following object into the unnamed temporary 
buffer. If preceded by a named buffer specification, “x, the text is 
placed in that buffer also. Text can be recovered later by a p or P. 


Redraws the screen with the current line placed as specified by the 
following character: CR specifies the top of the screen, . the center 
of the screen, and - at the bottom of the screen. A count may be 
given after the z and before the following character to specify the 
new screen size for the redraw. A count before the z gives the 
number of the line to place in the center of the screen instead of the 
default current line. 


Not used 
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APPENDIX A 

LIMITS AND EXTENSIONS 


COMPILER 

LIMITS 


char, unsigned char 

1 byte 

int, unsigned, short 

2 bytes 

long, unsigned long 

4 bytes 

float 

4 bytes 

double 

8 bytes 

any type* 

4 bytes 

Variable names: 

255 bytes (first 1 0 must be unique) 

Floating point: 

IEEE format: 32 bit float, 64 bit double, 80-bit 
intermediate 

Register variables: 

6 (2 pointer, 4 scalar) 


EXTENSIONS 

Structure passing, assignment and returning. 

In-line M68000 assembly (parsed and assembled by compiler). 

Character constants can be int and long size (ie. ’xx’ and ’xxxx’). 

The same structure member name can be used in more than one structure. 
Forward pointer references to Structures and Unions. 

Addition of types unsigned long and unsigned char. 
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LINKER 

Symbols: 256 character maximum 

Local and Global symbols are supported. 

Segment types: TEXT (code), DATA {initialized data), BSS 

(uninitialized data) 


LIBRARIAN 

Files per library: unlimited 

Operations: Add file. Delete file. Extract file, create random 

library, list files 
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B.1 COMMON LIBRARY FEATURES 


Introduction This section contains information that is common to all the 

protocol libraries described in Appendix B. The return codes 
described in this section are defined in the file cham.h in the 
directory a:/include. You will find it helpful to print a copy of 
the cham.h file for your reference. 


Sample Programs The following sections describe each library separately. At the 

end of each library description, you will find sample programs 
that utilize that library. Some sample programs utilize more 
than one library; these sample programs are cross-referenced 
instead of being repeated. 

Ail the sample programs can be found on the C Sample 
Program Diskette. The samples consist of three programs for 
each protocol. These samples are designed to be run alone 
or against each other as follows: 

XXXa.c Runs on a single or dual port machine on Port 
A. The program begins by initiating a 
transmission. It can be run against program 
XXXb.c (with XXXb.c on a second machine, or 
with both programs on the same dual port 
machine-one on Port A and one on Port B), 

XXXb.c Runs on a dual port machine on Port B. Can 
also run on a single port machine if the 
setport command is changed to call Port A 
instead of Port B. This program begins by 
waiting for a transmission. 

XXXab.c Runs on a dual port machine by running Port 
A against Port B. 
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FEP State Codes 


Error Codes 


The initpl or init anat function initializes the Chameleon 

Front End Processor (FEP) for a specific library. After using 
one of these functions, the state of the FEP is indicated by 
one of the following codes: 

Number Meaning 

100 FEP Is being used by another application and 
cannot be initialized by the simulation library. (The 
FEP is busy.) 

101 The FEP has not been Initialized by the simulation 
library (The FEP is currently free). 

102 FEP is initialized by the current simulation library. 
(The FEP Is running.) 


The error codes shown below may be returned by any of the 
protocol library functions. Note that FEP refers to the 
Chameleon Front End Processor. 

Number Meaning 

-200 Port is busy 

-201 FEP parameter error 

-202 FEP Parameter port 

-203 Not available on an ISDN interface 

-208 Code not found 

-209 FEP cannot be started 

-21 1 Transmission mode not valid 

-212 Timeout 

-213 No memory available 

-214 FEP Code read 

-21 5 FEP copier not found 

-216 FEP Code not loaded 

-217 Cannot halt FEP 

-218 No Ports 

-219 Internal error 

-220 FEP Load error 

-222 Undefined status 

-224 FEP Data not set (initpl not performed) 

-225 Unknown FEP error 
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Functions 


The functions listed in this section are included in all protocol 
libraries. The functions are described on the following pages: 


FUNCTION 

PAGE 

FLUSH 

B:1-4 

GETPHY 

B.1 -5 

GETPORT 

B.1 -6 

GETIME 

B.1 -7 

INITTIME 

B.1 -8 

PI RESET 

B.1 -9 

SETLEDS 

B.1-10 

SETPHY 

B.1-11 

SETPORT 

B.1-12 

SETTIMER 

B.1-13 

TIMER 

B.1.14 
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FLUSH 

Declaration 


Description 


Returns 


Note 


int flush{) 


This function clears all outstanding frames in the reception 
buffer. 


0 Successful 
3 Receive buffer overflow 

See global errors on page 

To clear a receive buffer overflow condition, perform an initpl. 
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GETPHY 

Declaration int getphyO 

Description This function indicates the setting of the physical lines. 

Returns 2-byte integer that can be interpreted using the figure below. 

See global errors on page B.1 -1. 






BYTEO 

(LSB) 






BIT: 

7 

6 

5 

4 

3 

2 

1 

0 

COTT Circuit No. 

PIN: 

105 

108 

140 

141 

104 

103 

114 

115 

V.24 Reference 

PIN: 

4 

20 



3 

2 

15 

17 

RS232 Signal Name 

SIG: 

RTS 

DTR 



RD 

TD 

scr 

SCR 





BYTE1 

(MSB) 






BIT: 

7 

6 

5 

4 

3 

2 

1 

0 

CQTT Circuit No. 

PIN: 

106 

107 

109 


125 

142 



V.24 Reference 

PIN: 

5 

6 

8 


22 




RS232 Signal Name 

SIG: 

CTS 

DSR 

CD 


Rl 
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GETPORT 

Declaration 

Description 

Returns 


int getportO 


This function returns which port is currently communicating 
with the library. Use the setport function to select the port. 


0 Port A selected. 

1 Port B selected 

See global errors on page B.1-1. 
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GETIME 


Declaration 


Description 


Returns 


Example 



#include <mtosux.h> 
int getime(msbfr) 
unsigned char *msbfr; 


This function gets the number of milliseconds since the 
system was started, msbfr is the address of a 6-byte buffer to 
receive the time value. 


NOERR Time value successfully copied 

BADPRM Unable to write into msbfr 


unsigned char mstime[6]; 
getime(mstime); 
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INITTIME 


Declaration 

Description 


Returns 


inittimeO 


This function initializes the .01 second and 1 second timers. 
The timers are set to their end time: 00 for the down 
counters, and FFFE for the up counters. You then can set the 
timers using the settimer command. 


See global errors on page B.1-1. 
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P1 RESET 

Declaration 


Range 


Description 


Returns 


int p1reset{kind) 
int kind; 


kind 0 Restart simulation 
1 Stop simulation 


This function either restarts or resets (stops) P1 
The restart function clears the reception buffer, 
function is similar to a hardware reset. 


0 Successful 
-1 Parameter error 

See global errors on page B.1-1. 


simulation. 
The stop 
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SETLEDS 


Declaration 


Range 


Description 


Returns 


int setleds(port) 
int port; 


port 0 Port A LEDs are displayed 
1 Port B LEDs are displayed 


For Dual Port machines, this function controls which port’s 
LEDs are displayed on the front panel of the Chameleon 32. 


0 Successful 

1 Invalid parameter 

2 Dual Port board not installed 

See global errors on page 
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SETPHY 

Declaration setphy(val) 

int val; 

Description This function sets the physical lines using val, which is bit- 

mapped as follows: 

SIMULATING PCE 



BIT: 

7 

6 

5 

4 

3 

2 1 0 

COTT Circuit No. 

PIN: 

106 

107 

109 


125 

142 

V.24 Reference 

PIN: 

5 

6 

8 


22 


RS232 Signal Name 

SIG: 

CTS 

DSR 

CD 


Rl 





SIMULATING DTE 



■ 

BIT: 1 

7 

6 

5 

4 

3 

2 1 0 

CCITT Qrcuit No. 

PIN: 

105 

108 

140 

141 



V.24 Reference 

PIN: 

4 

20 





RS232 Signal Name 

SIG: 

RTS 

DTR 






Returns See global errors on page B.1-1. 
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SETPORT 


Declaration 


Range 

Description 


Returns 


int setport(port) 
int port; 


port 0 Port A 
1 Port B 


This function sets the library to use either Port A or Port B. 
Use the getport function to determine which port is currently 
being used by the library. 


0 Successful 
-1 Parameter out of range 

-2 Attempted to select Port B on Chameleon with a single 
port (Port A) 

See global errors on page B.1-1. 
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SETTIMER 


Declaration 

int settimer(number, value) 
int number; 
unsigned int value; 

Range 

number 0 .01 seconds (counting down) 

1 .01 seconds (counting up) 

2 seconds (counting down) 

3 seconds (counting up) 

Description 

This function sets the timer specified by number to the indicated 
value. 

Returns 

0 Successful 

1 number outside of range 

2 inittime not performed 


See global errors on page B.1-1 
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TIMER 


Declaration 


Range 


Description 

Returns 


int timer(number) 
unsigned int(number) 

number 0 .01 seconds (counting down) 

1 .01 seconds (counting up) 

2 seconds (counting down) 

3 seconds (counting up) 

This function returns the value of a timer specified by number. 
See global errors on page B.1-1 
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B.2 BIT ORIENTED PROTOCOL EMULATION C LIBRARY 


Introduction The Bit-Oriented Protocol Emulation C Library (libbop.a) is 

valid for any Bit Oriented Protocol. It is in the \lib directory. 


There are two library functions which initialize the Chameleon 

Front End Processor: 

• The initpl function initializes the Chameleon to handle a 
maximum frame size of 2 kbytes. When initialized with 
this function, you can run Chameleon monitoring 
applications simultaneously to analyze the simulation 
traffic. 

• The initpl 8k function initializes the Chameleon to 

handle frames up to 8 kbytes, but does not allow you to 
run Chameleon monitoring applications simultaneously. 


The functions are described on the following pages: 


FUNCTION 

PAGE 

DISCARD 

B.2-2 

GET_NXLEN 

B.2-2 

GET__NXSTAT 

B.2-3 

INITP1 

B.2-4 

INITP1__8K 

B.2-5 

RECEIVE 

B.2-6 

SETFLG 

B.2-7 

TRANSMIT 

B.2-8 

TREADY 

B.2-9 


Also refer to Appendix B.1 for a description of common library 
functions and error codes. 

A sample program using the BOP library is provided at the end 
of this section. 
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DISCARD 

Declaration 

Description 

Returns 


GET_NXLEN 

Declaration 

Description 

Returns 


int discard { ) 


This function provides a means oif discarding a frame without first 
receiving it into a buffer. 

0 Frame discarded or no frame in buffer 
<0 standard error codes: FEP not started, etc. 

See also the global error codes on page B.1-1 . 

See GET_NXLEN, GET_NXSTAT. 


int get_nxlen { ) 


This function returns the length of the next frame to be passed from 
the FEP, providing you with information needed to optimize buffer 
usage and detect abnormally long frames that might otherwise 
exceed the allocated buffer space and overwrite part of the 
program. 


0 No new frame 

>0 Length of next frame to be received 
<0 standard error codes: FEP not started, etc. 

See also the global error codes on page B.1-1 . 
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GET_NXSTAT 

Declaration 

Description 

Returns 


int get_nxstat ( ) 


This function lets you ‘look ahead* at the status of the next frame to 
be received, allowing you to decide whether to receive the frame or 
discard it. 


0 No new frame 

1 Frame ok 

2 Frame received has a parity error 

3 Frame received contains an abort sequence 

<0 standard error codes: FEP not started, etc. 

See also the global error codes on page B.1-1 . 
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INITP1 


Declaration 


Range 


Description 


Note 


Returns 


int initp1{type, encode, bitrate, flag) 

int type; 

int encode; 

unsigned long bitrate; 

int flag; 


type 0 DCE 

1 DTE 

2 ISDN 

encode 0 NRZ 

1 NRZI 

bitrate SOL - 64000L 

flag 0 FF 

non-0 7E 


This function initializes the Front End Processor (PI) and loads 
its simulation software. The maximum frame size that can be 
handled by the simulator when initialized with this code is 2 
kbytes. 

The initpl 8k function enables you to initialize the Chameleon 
to handleTrames up to 8 kbytes .in size. However, when 
initialized for 8 kbyte frame size, you cannot run monitoring 
application simultaneously to analyze the simulation data. 


0 Successful 

-1 One or more parameter errors 
-2 P1 program file could not be loaded 

See also the global error codes on page B.1-1. 
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INITP1 


Declaration 


Range 


Description 


Returns 


8K 


int initpl ^8k(type, encode, bitrate, flag) 

int type; 
int encode; 
unsigned long bitrate; 
int flag; 


type 0 DCE 

1 DTE 

2 ISDN 

encode 0 NRZ 

1 NRZI 

bitrate 50L - 64000L 

flag 0 FF 

non-0 7E 


This function initializes the 8 kbyte frame size version of the 
Front End Processor (P1) and loads its simulation software. 

The maximum frame size that can be handled by the simulator 
when initialized with this code is 8 kbytes. However, you do 
not have the ability to simultaneously monitor the line. 

The initpl function initializes the Chameleon for frames up to 2 
kbytes in size and allows you to run monitoring applications 
simultaneously for analyzing the simulation data. 


0 Successful 

-1 One or more parameter errors 
-2 P1 program file could not be loaded 

See also the global error codes on page B.1-1. 
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RECEIVE 


Declaration 


Description 


Returns 


Example 


int receive(frame) 
char Irame; 


This function receives a frame from P1 and places the frame 
starting at the address pointed to by the passed variable 
frame. 

The external global variable rxlen is set to the length of the 
received frame. If rxlen = 0, then no frame was received. 


0 Good CRC or no frame waiting 

1 Bad CRC 

2 initpl not performed 

3 Overflow 

4 Abort frame received 

See also the global error codes on page 

When a RECEIVE buffer overflow error occurs (error code 3), 
use the Initpl function to clear the condition. The flush 
function wll not clear this condition. 


• • • 
do { 

rece1ve(f name) ; 

} while (rxlen == 0); 
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SETFLG 


Declaration 


Range 


Description 

Returns 


int setfig (flag) 
int flag; 


flag 0 Fill with FFs 

1 Fill with 7Es 


This function changes the idle fill pattern. 

See also the global error codes on page 
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TRANSMIT 

Declaration 


Range 


Description 


Returns 


int transmit(mocle, frame, length) 
int mode; 
char frame; 

Int length; 


mode 0 Good CRC 

1 Bad CRC 

2 Abort sequence 


This function transmits the number of bytes specified by the 
passed variable length, starting at the address pointed to by 
the passed pointer iframe. 


0 Successful 

1 P1 busy (transmitting previous frame) 

2 initpl not performed 

3 Parameter error 

4 Buffer overflow (to clear condition use initpl) 
See also the global error codes on page B.1-1. 
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TREADY 

Declaration 


Description 

Returns 


int treadyO 


This function returns the status of the transmitter. 


0 Transmitter is ready for next frame 

1 Transmitter is sending previous frame 

2 initpl not performed 

3 Overflow 

See also the global error codes on page B.1-1. 
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SAMPLE 

PROGRAMS 


There are three BOP Library sample programs provided on the 
C Sample Programs Disk: 

• bopab.c 

• bopa.c 

• bopb.c 


BOPAB.C This sample program runs on a Dual Port machine and 

demonstrates transmitting and receiving over a V.24 interface 
using the libbop.a library. 

#include <stdio.h> 

^include <v1deo.h> 

#include <cham.h> 

/♦ 

♦ INITIALIZE PORTS A AND B (LOAD FRONT END PROCESSORS) 

•/ 

init_ports( ) 

{ 

int err; 

SETUP PORT "A*» 

if ( (err=setport(PORTA)) 0 ) { 
pr1ntf( "ERROR: setport * %d\n", err); 
ex1t(0); 

} 

if ( {err=initpl(OCE,NRZ, 96001, F1LL7E)) != 0 ) { 
printf("ERR0R: initpl = Xd\n", err); 
exit(O); 

} 

/••••••••••• SETUP PORT "B" ••••••••••••/ 

if ( (err=setport( PORTS)) != 0 ) { 
printf("ERROR: setport = Xd\n", err); 
e*it(0); 

} 

if ( (err=initpl(DTE.MRZ, 96001, FILL7E)) != 0 ) { 
printf( "ERROR: initpl = Xd\n", err); 
exit(O); 

} 

} 


/• 

• RECEIVE DATA FROM THE PORT SPECIFIED 

•/ 

receive_data(port) 
unsigned char port; 
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extern unsigned int rxlen; /• global variable for receive data length •/ 
unsigned char rxbuf[128]; 
int i ; 

setport(port) ; /♦ activate appropriate port •/ 
rxlen = 0; 

/♦ WAIT FOR DATA •/ 

while (rxlen==0) /♦ if rxlen=0 then no data was received •/ 
receive(rxbuf ); 

for( i=0; i<rxlen; i++) 

printf("Xx " , rxbuf [i]) ; /• print results of data transfer •/ 

} 


/♦ 

* TRANSMIT DATA OUT THE PORT SPECIFIED 

♦/ 

send_data( port, buffer) 
unsigned char port, •buffer; 

{ 

int err; 

setport(port) ; /• activate appropriate port •/ 
if ( (err=transinit(600D_CRC, buffer, 100) ) != 0) { 
printf(FRED); /• change text color ♦/ 
switch (err) { 
case 1: 

printf ("\ntransinit=Xd; PI busy sending previous f rameVn" ,err) ; 
break; 
case 2: 

printf ('*\ntransmit=%d; Initpl not performedXn" ,err) ; 
break; 
case 3: 

printf ("\ntransinit=%d; Parameter errorXn" ,err); 
break; 
case 4: 

printf ( '*\ntransmit=%d; Buffer overflow, do a PlresetXn” ,err) ; 
break; 

} 

printf ( FWHITE) ; /♦ change text color back to normal •/ 

} 

} 


/• 

• PROMPT USER FOR STATUS OF TRANSMITTER 

•/ 

query_transmit_status( ) 

i 

extern long _stdvt; 
unsigned char ans; 
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ohile (1) { 

printf ( "\n%sPress RETURN to Transmit or any other key for StatusXsNn" ,FYELLOW,FWHITE) ; 
if ((ans=getcwt(_stdvt)) 1= '\r') 
switch (treadyO) { 
case 0: 

printf ("XsTransmitter is ready to send the next f rame%s\n**,FGREEN,FWHITE); 
break; 
case 1: 

printfC’XsPl busy sending previous frameXs\n*,FRED,FWHITE); 
break; 
case 2: 

printf ("Xslnitpl not perf ormedXsXn" , FRED, FWHITE) ; 
break; 
case 3: 

printf ("XsBuffer overf lowXsKn" , FRED, FWHITE) ; 
break; 

} 

else 

break; /• exit routine ♦/ 

} 

} 


ina1n( ) 

{ 

unsigned char atrans[100]; /♦ transmit array •/ 
int i; 

printf (CLEARS) ; /♦ clear the screen ♦/ 

/• INITIALIZE BOTH FRONT END PROCESSORS •/ 
init_ports( ) ; 



/♦ TRANSFER DATA FROM PORT A TO PORT B ♦/ 

for ( i=0;i<=99; i++) 

atrans[i]=0x66; /♦ store hex 66 into transmit array ♦/ 
query_transmit_status{ ) ; /♦ check status before transmitting ♦/ 
send_data(PORTA,atrans) ; /• transmit data out port A •/ 
receive_data(PORTB) ; /♦ receive data on port B ♦/ 

/• TRANSFER DATA FROM PORT B TO PORT A •/ 
for ( i=0; i<=99; !+•*“) 
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atrans[i]=0x22; /• store hex 22 into transmit array •/ 
query_transmit_status( ) ; /♦ check status before transmitting •/ 
send_data( PORTS, atrans ) ; /• transmit data out 'port B ♦/ 
recei ve_data( PORTA ) ; /♦ receive data on port A •/ 

printf ("XnXn" ) ; 

} 
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This sample program demonstrates transmitting and receiving 
on Port A over a V.24 interface using the libbop.a library. If 
this program is run against bopb.c, they must both be run in 
background mode. 


stdvt; 

extern unsigned int rxlen; global variable for receive data length */ 

unsigned char atrans[100],rxbuf[128]; /• transmit & revieve arrays •/ 
int result,err,1 ; 
unsigned char c; 

/• SET THE ACTIVE PORT TO -A" •/ 
if( (err=setport(PORTA)) != 0 ) { 
pr1ntf( "ERROR: setport = Xd\n", err); 
ex1t(0); 

} 

if ( (err=initpl(DCE,NRZ, 96001, F1LL7E)) 1= 0 ) { 
printf( "ERROR: initpl = Xd\n*, err); 
exit(0) ; 

} 

for ( 1*0; 1<*99; 1++) 

atrans[1]*0x66; /♦ store hex 66 Into transmit array •/ 

printf{"\n hit RETURN to send the data out of port 'A'\n"); 
getchar(); 

result*transm1t(G000_CRC,atrans, 100) ; /♦ transmit 100 hex 66 & get result ♦/ 
printf{"\nresult of transmit=%d\n" , result) ; 

printf { "\nWaiting to receive data on port ’A’\n"); 

RxLEN*0; 

/• WAIT FOR DATA •/ 
while ( rxlen*=0) { 

receive( rxbuf ) ; /• if rxlen*0 then no data was received */ 

if( (c=getch{_stdvt) ) =* 'q' || c *= 'Q' ) exit(O); /• fail safe ♦/ 


for{ 1*0; Krxlen; 1++) 

printf("Xx ".rxbuf[i]); /• print results of data transfer ♦/ 

printf ("\n hit RETURN to exit the prograroXn"); 
getchar(); 


BOPA.C 


#include <stdio.h> 
^include <cham.h> 
ma1n( ) 

{ 

extern long 


} 
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BOPB.C This sample program demonstrates transmitting and receiving 

on Port B over a V.25 interface using the libbop.a library. If 
this program is run against bopa.c, they must both be run in 
background mode. 

#include <std1o.h> 

^include <cham.h> 
ma1n( ) 

{ 

extern long _stdvt; 

extern unsigned int rxlen; /♦ global variable for receive data length ♦/ 
unsigned char atrans[100], rxbuf[128]; /* transmit & recieve arrays ♦/ 
int result, err, i ; 
unsigned char c; 

/♦ SET THE ACTIVE PORT TO "B" •/ 
if{ (err=setport(PORTB)) 1= 0 ) { 

printf ("ERROR; setport = Xd\n", err); 
exit(O); 

} 

if ( (orr=initpl(DTE, NRZ, 96001 ,FILL7E)) 1= 0 ) { 
printf ("ERROR: initpl = %d\n", err); 
exit(O) : 

} 

printf ("\nWaiting to receive data on port 'B*\n"); 

RxLEN^^O; 

/• WAIT FOR DATA ♦/ 
while (rxlen==0) { 

receive(rxbuf ); /• if rxlen=0 then no data was received ♦/ 

if( (c=getch(_stdvt)) == II c == ’Q' ) exit(O); /• fail safe •/ 

> 

for( i=0; i< rxlen ; i+*t") 

printf("Xx ",rxbuf[i]); /• print results of data transfer ♦/ 
for (i*0;i<=99;i++) 

atrans[i]=0x77; /• store hex 77 into transmit array 

printf ("\n hit RETURN to send the data out of port ’B’Xn"); 
getcharO; 

result=transmit(GOOO_CRC,atrans, 100) ; /• transmit 100 hex 77 & get result ♦/ 
printf ( "\nresult of transmit=Xd\n" , result) ; 

printf ("\n hit RETURN to exit the programXn" ) ; 
getcharO; 

} 
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B.3 LAPD LIBRARY 


Introduction The LAPD Library is valid for the CCITT automatic Q.921 

frame level. It is called liblapd.a and it is in the Mib directory. 
The LAPD library fully simulates AT&T Specification 5E4 LAPD 
and includes the following features: 

• Supports up to three SAPIs and three TEIs, plus the 
broadcast TEI 

• Automatically responds with received SAPI and TEI 

• Transmits and receives XID and Ul frames 

The LAPD library functions are described on the pages below. 


FUNCTION 

PAGE 

GET.MOD 

B.3-4 

GET.RNTEI 

B.3-5 

GET.RSAPI 

B.3-6 

GET-SCONFIG 

B.3-7 

GET.SIM 

B.3-8 

INITP1 

B.3-9 

RECEIVE 

B.3-1 0 

RESTARTSIM 

B.3-1 2 

SETFLG 

B.3-1 3 

SET.BIT.RATE 

B.3-14 

SET.MOD 

B.3-1 5 

S-N200 

B.3-1 6 

S-N201 

B.3-1 7 

SET.NET 

B.3.18 

SET.RNTEI 

B.3-1 9 

SET.RSAPI 

B.3.20 

SET.SAPI 

B.3.21 

SET.SCONFIG 

B.3.22 

SET.SUB 

B.3.24 

S-T200 

B.3.25 

S.T203 

B.3.26 

SET.TEI 

B.3.27 

SET.WINDOW 

B.3.28 

SLOF 

B.3.29 

SLON 

B.3.30 

STATUS 

B.3.31 

STOPSIM 

B.3.32 

TRANS 

B.3-33 

TRANSMIT 

B.3.34 

TRUI 

B.3-35 

TRXCNI 

B.3.36 

TRXRNI 

B.3.37 

TRXIDC 

B.3.38 

TRXIDR 

B.3.39 


Refer to Appendix B.1 for a list of common library functions. 
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Automated 

Functions 


When a command frame is received with any combination of 
the three user-defined SAPI’s and TEI’s, or one of the three 
SAPI’s and the broadcast TEI, the response is autc matically 
given a matching SAPl/TEl combination. Thus, you no longer 
have to simulate support of more than one TEI. 

Since this version of LAPD Simulation can receive a number of 
different frame types from a number of sources that contain an 
information field, a frame status byte has been added at the 
beginning of every data packet passed to your program. 
Refer to the receive function for the frame status byte 
interpretation. 

You can also set and display the status configuration byte 

using function in the LAPD library. Refer to the set ^sconfig 

and get ^sconfig library functions for more information and for 

an interpretation of the configuration status byte. 

The simulator is configured to assume that an XID frame 
without an l-field is the link monitor and automatically 
responds. Therefore no status is in the reception buffer when 
an XID frame without an l-field is received. 
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Timeouts 


Defining Links 


Note 


The library timeouts vary from 15 seconds to 45 seconds. 
When you receive a timeout return from any of the functions, 
you should stop and reset the Front End Processor, using the 
function plreset(l) or initp1(). If you continue to experience 
problems, reset the Chameleon 32. 

To define a link, the following four functions are used: 

• SET TEI 

• SET~SAPI 

• SET~RNTEI 

• SET“RSAPI 

In the Single Link LAPD library, you use SET ^TEI and 

SET^SAPI to set the TEI and SAPI values for the link. 

SET RNTEI and SET RSAPI are used in conjunction with 
SET”TEI and SET_SAPl. The SET RSAPI and SET RNTEI 
commands allow you to select up tolhree user-define3” SAPIs 
and TEIs. One of the defined SAPIs and TEI can then be 
selected as the transmit value for the link. The three user- 
defined SAPIs are referred to as RSAPIO, RSAPli , and RSAPI2. 
Likewise, the three user-defined TEIs are referred to as 
RNTEIO, RNTEI1, and RNTEI2. 

To communicate on a given link, use SET SAPI and SET TEI . 
to select the RSAPI and RNTEI with the desired SARI and”TEl 
values. For example, if you use SET RSAPI to select 0, 16, 
and 63 as the user-defined SAPIs, an'd' SET__RNTEI to select 
0, 10 and 20 as the user-defined TEIs, you would have the 
following array of values available; 



RTE10 = 0 

RTE11 = 10 

RTEI2 = 20 

RSAPIO = 0 

0,0 

0,10 

0,20 

RSAPI1=16 

16,0 

16,10 

16,20 

RSAPI2 = 63 

63,0 

63,10 

63,20 


You would then use SET__SAPI and SET__TEI to make one of 
these links active. For example: 

SET_SAPi(63) Sets the transmit SAPI value to 63 

SET__TEI(127) Sets the transmit TEI value to 127 


Only one link at a time can be in the multi-frame alignment 
state. 
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GET_MOD 

Declaration 

Description 

Returns 

Sample Usage 


int get_mocl () 

This function returns the current modulus. The modulo may 
change when receiving SABMs or SABMEs. 

0 Mods 

1 Modi 28 

See also the global error codes on page B.1>1. 


printf ("\nResult from get mod=»%d\n", get mod 0); 

} 
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GET_RNTEI 

Declaration 

Range 

Description 


Returns 

Sample Usage 


int get rntei (val) 

int vai; 


val 0-2 


This function returns the value of a user-defined TEl used for 
reception. 

The TEl (Terminal Endpoint Identifier) is a value assigned to 
and may be associated with a single terminal and a given 
point-to-point data link connection. At any time, a given 
terminal endpoint (TE) may contain one or more TEIs. 

This value may be assigned by the carrier at the time of 
equipment installation, or may be automatically assigned on a 
call-by-call basis. The broadcast value is associated with ail 
user-side data link entities with the same SAPI, regardless of 
other assigned vaiue(s). 


0-127 (Value of TEl val ) 

-1 val outside of range 

See also the global error codes on page B.1-1. 


{' 

} 


printf (”\n Result from get rntei==%d\n”, get mtei (0)); 
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GET_RSAPI 

Declaration 

Range 

Description 

Returns 

Sample Usage 


int get rsapi (val) 

int val; 


val 0 -2. 


This function returns the value of a user-defined SAPI used for 
reception. The SAPI (Service Access Point Identifier) 
indicates the layer two service type requested or supported. 


0-63 Receive SAPI value 
-1 val outside of range 

See also the global error codes on page B.1-1. 


printf ("\nResult from get rsapi ==%d\n'*, get rsapi (0)); 

} 
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GET_SCONFIG 

Declaration int get config () 


Description This function returns the status configuration byte, interpreted 

as shown below. 


76543210 


Bit 


Reserved 


Interframe Fill 

0 = Set interframe fill to value 7E 

1 = Set interframe fill to value FF 


Address Restricted 

0 = Unrestricted (Accept responses matching user- 

defined SAPIs and TEI and broadcast TEIT) 

1 = Restricted (Restrict received responses to the 

transmit SAPI and TEI). 


Status Changing Frames 

0 =s Poll normal (Set poll bit normal on status changing 

frames SABM(E) and DISC) 

1 = Poll set (Set poll bit on status changing frames 

SABM(E) and DISC.) 


SABM(E) Response 

0 = UAoniy. Stop generating SABM(E) collisions. 

1 = UAandSABM(E). Generate SABM(E) collisions. 


XID Poll Bit 

00 = No XID frames polled. 

01 = Poll only XID frames without l-fields. 

10 = Poll only XID frarhes with l-fields. 

11 = Poll all XID frames 


XID Exchange 

0 = Stop transmitting XID's on T203 timeout. 

1 = Transmit XID command on T203 timeout. 


Returns 


Status configuration byte. 


See also the global error codes on page B.1-1. 


Sample Usage 

printf ("\nResultfrom get__sconfig==%x\n", get__sconfig 0): 


Tekelec 


B.3-7 


Version 2.4 










Chameleon 32 C Manual 


Appendix B. 3: LAPD Library 


GET_SIM 

Declaration 

Description 

Returns 

Sampie Usage 


int get sim () 

This function returns the side being simulated. 

0 Network 

1 Subscriber 

See also the global error codes on page 

printf ("\nResult from get__sim==%d\n”, get sim 0); 
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INITP1 

Declaration 

Range 


Description 

Returns 


Sampie Usage* 


int initpl (interface, station, encode, bitrate) 
int interface, station, encode; 
long bitrate; 


interface 

0 

DCE (V-type) 


1 

DTE (V-type) 


2 

ISDN (Valid only if the Primary Rate or Basic 
Rate Interface is physically installed) 

station 

0 

Network 


1 

Subscriber 

encode 

0 

NRZ 


1 

NRZI 

bitrate 

Integer value in the range 50-64000 


This function initializes the Front End Processor and loads its 
simulation software. 


0 Successful 
-1 Parameter error 

See also the global error codes on page B.1-1. 


printf ("\nResult from initpl*=Xd\n" , in1tpl(0,l«0,16000L)); 


DCE 


NRZ 


Subscriber 


*NOTE: The program must include cham.h for the definition. 
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RECEIVE 

Declaration 


Description 


Returns 


extern int rxlen; 
int receive (rioc) 
char ‘rloc; 


This function receives an l-field from the data link layer, and 
places it starting at the address pointed to by the passed 
variable rioc. A status byte added in front of the received 
information which can be interpreted as shown below. 

The external global variable rxlen will be set to the length of 
the received frame. If rxlen = 0, no l-frame was received. 


7 6 5 4 3 2 1 0 


BIT 



0 Successful or no frame waiting 

2 Initpl not performed 

4 PI is busy 

See also the global error codes on page B.1-1. 
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Sample Usage 


char rxbuf [512]; 
int a; 

extern int rxlen; 

do { /•If rxlen = 0, then no data was received) ♦/ 

a-receive (&rxbuf[0]); 

} while (rxlen==0); 

printf( "Receive len==Xd, dl status==Xx, Data Status=*%x\n" , rxlen, a, rxbuf [0]); 
for(a*l; a < rxlen; a-f+) 

printf("Xx " , rxbuf [a]); 
puts("\n"); 

} 
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RESTARTSIM 

Declaration 

Description 

Returns 

Sample Usage 


int restartsimO 


This is equivalent to plreset{0). This function restarts P1 
simulation. The restart function will bring the link down, as if 
the initpl command had been carried out. 


0 Successful 

1 Time out 

See also the global error codes on page B.1-1. 


{' 

} 


printf ("\nResultfrom Restartsim==%d\n", restartsim Q): 
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SETFLG 

Declaration 

Range 

Description 

Returns 

Sample Usage 


int setfig (flag) 
int flag; 

0 Fill with FF 

Non-zero Fill with 7E 


This function changes the idle fill pattern. 

0 Successful 

1 Time out 

See also the global error codes on page 


printf ("VnResult from setfig *=%d\n", setfig (0)); 

} 
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SET_BIT_^ 

Declaration 

Range 

Description 

Returns 

Sampie Usage 


RATE 


int set bit rate (rate) 

long rate; 


rate 50 - 64000 


This function sets the bit rate. No check of the range is done. 
It is your responsibility to verify that you enter a valid bit rate. 


0 Successful 

1 Error 

See also the global error codes on page B.1-1. 


{■ 

printf ("\nResult from set bit rate* =%d\n", set bit rate (9600L)); 
} ~ 
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SET MOD 


Declaration int set mod (val) 

int val; 


Range val 0 Mods 

1 Mod 128 


Description This function sets the modulus of N{S) and N(R). 


Returns 0 Successful 

-1 val outside the range 0-1 
1 Time out 

See also the global error codes on page B.1-1. 


Sample Usage 

printf ("\nResult from set mod==%d\n”, set mod (0)); 
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S_N200 

Declaration 

Range 

Description 

NOTE 

Returns 

Sample Usage... 


int s n200(val) 
int val; 


val = 1 to 512 


This function sets the value of N200, the number of 
retransmissions. This value defines the maximum number of 
frame retransmissions that can occur after successive lapses 
of the T201 timer before declaring the link unattainable, and 
sending disconnects. 

This function is also represented by set n1 in the sample 
programs on pages B.3-43 and B.3-45. This representation of 

the S N200 function is included in the LAPD Library to ease 

the transition from HDLC to LAPD programming and aid in the 
conversion of HDLC programs to run LAPD. 


0 Successful 

1 Time out 

See also the global error codes on page B.1-1. 


{ 

printf ("\n Result from s n200==%d\n", s n200 (3)); 

} 
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S_N201 

Declaration 

Range 

Description 

NOTE 

Returns 

Sample Usage... 


int s n201 (val) 

int val; 


val 1 - 512 


This function sets the value of N201, the maximum size of a 
packet in bytes. When the system receives a frame, it checks 
the value of the N201 variable. If the system receives a frame 
longer than N201, it automatically sends a frame reject 
(FRMR). 

This function is also represented by set n2 in the sample 
programs on pages B.3-43 and B.3-45. This representation of 

the S N201 function is included in the LAPP Library to ease 

the transition from HDLC to LAPD programming and aid in the 
conversion of HDLC programs to run LAPD. 


0 Successful 

-1 val outside the range 1-512 

1 Time out 

See also the global error codes on page B.1-1. 


printf.("\nResultfrom s •n201*®%d\n”, s n201 (128)); 

} 
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SET NET 


Declaration int set net () 

Description This function sets simulation of a network. When the 

Chameleon 32 emulates a network, it sends commands with 
the C/R bit set to one, and responds with the C/R bit set to 
zero. It sends the selected SAPI and TEI with the C/R bit 
automatically set in accordance with CCITT Q. 921 . 


Returns 0 Successful 

1 Time out 

See also the global error codes on page 


Sample Usage 

printf ("\nResult from set net==%d\n", set net ()); 

} 
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SET_RNTEI 

Declaration 

Range 

Description 


Returns 

Sample Usage 


int set rntei (val, tei) 
int val, lei; 


val 

0-2 

tei 

0-255 


This function specifies up to three TEI values that can be 
received by the RECEIVE function. Three user-defined TEls 
and one broadcast TEI (127) can be defined at any one time. 
Once set, one of the defined TEls can be selected as the 
transmit TEI using the SET__TE1 function. 

To disable a user-defined TEI, use SET RNTEI to assign an 
invalid value to the TEI, or assign a TEI \^ue that is already in 
use. 


0 Successful 

1 Time out 

-1 Invalid value 

See also the global error codes on page B. 1-1. 


(at program initiation) 
init{ ) 

setport(PORTA); 

set rntei(0,PHONE A); 

set rntei(1 ,TA_A); 

}■ 
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SET_RSAPI 

Dejiaration 


Range 


Description 


Returns 


Sample Usage 


int set rsapi (val, sapi) 

int vai, sapi; 

val 0-2 SAPI number 

sapi 0-63 SAPI value 


Standard SAPI values are: 

0 Call control procedures 

16 Packet communications procedures 

63 Management procedures 


This function selects 1-3 RECEIVE SAPI values. The SAPI 
(Service Access Point Identifier) indicates the layer two service 
type requested or supported. One of these defined SAPIs can 

be selected as the transmit SAPI using the SET SAPI 

function. 

To disable a user-defined SAPI, use SET__RSAPI to assign an 
invalid value to the SAPI, or assign a SAPI value that is already 
in use. 


0 Successful 

1 Time out 
-1 Invalid val 

See also the global error codes on page B.1-1. 


{■ 

printf {"NnResult from set rsapi® ®%d\n", set rsapi (1,63)); 

} 
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SET SAPI 


Declaration 


Range 

Description 


Returns 


Sample Usage 


int set sapi(val) 

int val; 

vaJ 0-63 


This function sets the supported SAPI for transmission. The 
SAPI (Service Access Point Identifier) indicates the layer two 
service type requested or supported. 

Standard SAPI values are: 

0 Call Control procedures 

16 Packet Communication procedures 

63 Management procedures 


0 Successful 

-1 val outside of range 

1 Time out 

See also the global error codes on page B.1-1. 


{■ 

printf (*\nResult from set sapi®*%d\n", set sapi (0)); 

} 
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SET_SCONFIG 

Declaration int set ^sconfig (byte) 

int byte; 


Range 

Description 


byte 0 - 255 

This function sets the status configuration byte which is a bit- 
mapped control configuration byte shown in the figure below. 


76543210 


Bit 


Reserved 


Interframe Ril 

0 = Set interframe fill to value 7E 

1 = Set interframe fill to value FF 


Address Restricted 

0 = Unrestricted (Accept responses matching user- 

defined SAPIs and TEI and broadcast TEQ 

1 = Restricted (Restrict received responses to the 

transmit SAPI and TEI). 


Status Changing Frames 

0 = Poll normalTSet poll bit normal on status changing 

frames SABM(E) and DISC.) 

1 = Poll set (Set poll bit on status changing frames 

SABM(E) and DISC.) 


SABM(E) Response 

0 = UA only. Stop generating SABM(E) collisions. 

1 = UAancfSABM(E). Generate SABM(E) collisions. 


XID Poll Bit 

00 = No XID frames polled. 

01 = Poll only XID frames without l-fields. 

10 = Poll only XID frames with l-fields. 

11 = Poll all XID frames 


XID Exchange 

0 = Stop transmitting XID's on T203 timeout. 

1 = Transmit XID command on T203 timeout. 
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Returns 


Sample Usage 


0 Successful 

1 Time out 

See also the global error codes on page B.1-1. 


{■ 

printf {"\nResult from set sconfig==%d\n", set sconfig (0x7A)); 

} 


The hex value 7A is represented in binary as: 

0111,1010 


which sets the status configuration byte as follows: 


Bit 7 
Bit 6,5 
Bit 4 
Bits 
Bits 
Bit 1 
BitO 


0 Stop transmitting XID frames on T203 timeout 
1 1 Poll all XID frames 

1 Generate SABM(E) collisions 
1 Poll set 

0 Unrestricted address 

1 Interframe fill = FF 
Reserved 
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SET_SUB 

Declaration 

Description 

Returns 

Sample Usage 


int set sub () 


This function sets simulation of subscriber. When the 
Chameleon 32 emulates a SIMP/L LAPD subscriber, it sends 
commands with the C/R bit set to zero, and responses with 
the C/R bit set to one. It sends the selected SAPI and TEI 
with the C/R bit automatically set in accordance with CCITT Q. 
921. 


0 Successful 

1 Time out 

See also the global error codes on page B.1-1. 


{■ 

printf ("NnResult from set sub==%d\n", set sub 0)i 
} “ ~ 
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Declaration 

Range 

Description 


NOTE 

Returns 

Sample Usage 


Appendix B. 3: LAPD Library 


s t200{val) 
irir val; 

val In units of seconds; any int value (0 - OxFFFF) 


This function sets the value of the T200 frame level timer and 
defines the maximum timeout period permitted between 
sending a frame and receiving an acknowledgment. The timer 
is started by the station when it sends any command frames. 
If T200 expires before the station receives a response, it 
retransmits the message and restarts the timer and 
decrements N200. When the T200 expires, the frame is 
retransmitted N200 - 1 times at T200 intervals. Following an 
N200 - 1 number of retransmissions, the station takes 
appropriate recovery action. If T200 expires and outstanding 
frames remain unacknowledged, the station re-arms T200 and 
sends an appropriate Supervisory Command Frame with the 
poll bit set. 

T200 is expressed in units of seconds. The T200 timer can 
be disabled by setting it to zero. Disabling the T200 timer 
enables you to test a device without receiving a link status 
check or retransmitted frame while performing a manual 
operation or test measurement. 

This function is also represented by t1 in the sample programs 
on pages B.3-43 and B.3-45. This representation of the 
S_T200 function is included in the LAPD Library to ease the 
transition from HDLC to LAPD programming and aid in the 
conversion of HDLC programs to run LAPD. 


0 Successful 

1 Time out 

See also the global error codes on page B.1-1. 


printf("\nResultfrom s t200==%d\n". s t200 (4)); 

} 
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S_T203 

Declaration 

Range 

Description 


NOTE 

Returns 

Sample Usage 


s t203(val) 
inT val; 


val In units of seconds; any int value (0 - OxFFFF) 


This function sets the value of the T203 frame level timer. The 
T203 variable defines the maximum amount of time allowed 
between the transmission of frames. If this timer expires, the 
Chameleon 32 tests the link conditions by transmitting an RR, 
RNR, REJ or XID command, depending on the current state 
and configuration. 

The T203 timer can be disabled by setting it to zero. Disabling 
the T203 timer enables you to test a device without receiving a 
link status check or retransmitted frame while performing a 
manual operation or test measurement. 

This function is also represented by set t2 in the sample 
programs on pages B.3-43 and B.3-45. This representation of 

the S T203 function is included in the LAPD Library to ease 

the transition from HDLC to LAPD programming and aid in the 
conversion of HDLC programs to run LAPD. 


0 Successful 

1 Time out 

See also the global error codes on page B.1-1. 


{■ 

} 


printf ( "\nResult from s_t203= =% d\n " , s t203 (1 00)); 
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SET_TE1 

Declaration 

Range 

Description 


Returns 

Sample Usage 


int set ^tei (val) 

int val; 


val 0 - 127 


This function sets the transmit TEI. The TEI (Terminal 
Endpoint Identifier) is a value assigned to and may be 
associated with a single terminal and a given point-to-point 
data link connection. At any time, a given terminal endpoint 
(TE) may contain one or more TEIs. 

This value may be assigned by the carrier at the time of 
equipment installation, or may be automatically assigned on a 
call-by-call basis. The broadcast value is associated with all 
user-side data link entities with the same SAPI, regardless of 
other assigned vaiue<s). 


0 Successful 

-1 val outside of range 

1 Time out 

See also the global error codes on page B.1-1. 


{■ 

printf ('\nResult from set tei==%d\n", set tei (1)); 

} 
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SET WINDOW 


Declaration int set__window (val) 

int val; 


Range val 1-7 


Description This function sets the window size for the frame level. The 

WINDOW variable defines the maximum number of 
sequentially numbered l-frames that the transmitting side can 
have outstanding (unacknowledged) at any given time. 


Return 0 Successful 

-1 val outside the range 1-7 
1 Time out 

See also the global error codes on page B.1-1. 


Sample Usage 

{ 

print! ("NnResulf from set window® *%d\n", set window (3)); 

} 
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SLOP 


Declaration 


Description 


Returns 


Sample Usage 


int slof() 


This function disconnects the link at the frame level by sending 
a Disconnect. 


0 Successful 

1 Time out 

See also the global error codes on page 


{■ 

printf (*\nResult from slof==%d\n*, slof 0): 

} 
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SLON 


Declaration int slon() 


Description This function attempts to establish a link at the frame level by 

sending a SABM or SABME, depending on the selected 
modulus. 


Returns 0 Successful 

1 Time out 

See also the global error codes on page B.1-1. 


Sample Usage 

printf ("\nResult from slon==%d\n", slon 0): 

} 
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STATUS 

Declaration 

Description 

Returns 


Sample Usage 


int statusO 


This function returns a value indicating the status of the frame 
level. 


0 Disconnected 

1 Link connection requested 

2 Packet reject state 

3 Link disconnection 

4 Information transfer state 

5 Local station busy 

6 Remote station busy 

7 Local & remote station busy 

8 Remote station not responding 

See also the global error codes on page 


{■ 

printf (AnResult from status® *%d\n*, status ()): 

} 
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STOPSIM 

Declaration 

Description 

Returns 

Sample Usage 


int stopsimO 


This function stops P1 simulation which is similar to a 
hardware reset. 


0 Successful 

1 Time out 

See also the global error codes on page B.1-1. 


{■ 

} 


printf ("\nResult from stopsim=®%d\n", stopsim 0); 
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Declaration 


Range 


Description 


Returns 


Sample Usage 


Appendix B.3: LAPD Library 


int trans (stat, frame, len) 
char “frame; 
int stat, len; 


stat 0x80 1-Frame 
0x81 Ul frame 
0x82 XI D Command frame 

0x83 XI D Response frame 

*frame any valid pointer 
fen 0-511 


This function transmits a frame where the type of frame is 
identified by stat. “frame is any valid pointer and len is in the 
range 


0 Successful 

1 PI busy (transmitting previous packet) 

2 Initpl not performed 

3 Link not established for an 1-Frame 
5. Time out 

Value returned from trxcni() is returned if an XI D command 
frame is transmitted with len = 0 

Value returned from trxrni() is returned if an XID response 
frame Is transmitted with len =0 

See also the global error codes on page B.1-1. 


printf (‘VnResult from trans==%d\n*, trans (0x80,"ABCD",4)); 

} 
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TRANSMIT 


Declaration 


Description 


Returns 


Sampie Usage 


int transmit (packet, length) 
char *packet; 
int length; 


This function transmits the number of bytes specified by the 
passed variable length, starting at the address pointed to by 
the passed variable jacket 


Transmit calls and returns the value returned by this call: 
trans(iFRAME, packet, length). 

See also the global error codes on page 


printf ("\nResult from transmit® =%d\n", transmit (**ABCD",4)); 

} 
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TRUI 


Declaration 


Description 


Returns 


Sample Usage 


trui (xioc, xien) 
char *xloc; 
int xien; 


This function transmits an unnumbered l-frame. xIoc is the 
location of data, xien is the length of the data field. 

In keeping with Q.921, a Ui frame can be transmitted without 
first setting multiple frame mode. In other words, it is not 
necessary to exchange SABM(E) and UA frames before 
transmitting a UI frame. 


TRUI calls and returns the value returned by this call: 
trans(UI, packet, length) 

See also the global error codes on page B.1-1. 


printf ('NoResult from trui*=%cl\n"; trui (&buffer,4)); 

} 
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TRXCNI 

Declaration 

Description 

Returns 

Sample Usage 


int trxcni () 


This function transmits an XI D command frame without an I 
field. 


0 Successful 

1 Time out 

See also the global error codes on page B.1-1. 


• •• 

{ 

printf ("\nResult from trxcni® =%d\n*, trxcni 0); 

} 
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TRXRNI 

Declaration 

Description 

Returns 

Sample Usage 


int trxrni () 


This function transmits an XID response frame without an I- 
field. 


Values returned are as follows: 

0 Successful 

1 Time out 

See also the global error codes on page 


{■ 

printf {"\nResult from trxrni==%d\n", trxrni 0): 

} 
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TRXIDC 


Declaration 


Description 


Returns 


Sample Usage 


int trxidc (xioc, xlen) 
char *xloc; 
int xlen; 


This function transmits an XID command frame with the 1-Field 
defined by the user-program, located at xIoc in the memory 
and of xlen length. 


TRXIDC calls and returns the value returned by this call; 
trans(XiDC, xioc, xlen) 

See also the global error codes on page B.1-1. 


{‘ 

printf ("'nResult from trxidc* *%d\n", trxidc (’ABCD*,4)); 

} 
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TRXIDR 

Declaration 


Description 


Returns 


Sample Usage 


int trxidr (xioc, xlen) 
char *xloc; 
int xlen; 


This function transmits an XI D response frame with the 1-Field 
defined by the user-program, located at x/oc in the memory 
and of xlen length. 

This response frame is under control of the user-program 
because of the indefinite nature of the 1-Field. The received 
data must be closely monitored to generate a timely response 
to the XID command. 

This TRXIDR command transmits an XID response frame with 
a copy of the last received SAPI and TEI. In this way, the 
process of preparing the SAPI-C/R combination takes less 
time and the remote unit receives the response it is expecting. 

In light of this, it is highly recommended that SIMP/L LAPD 
application programs be designed to monitor received frames 
and respond immediately when an XID command is received. 
If an XID response is sent at a different time, the remote unit 
may treat it as a command, if the last received frame was a 
response. 

if an XID command is received without an l-field, it is assumed 
to be a link monitor frame. In this case, an XID response with 
matching SAPI and TEI is automatically transmitted without an 
l-field. This relieves the programmer of having to generate 
responses in applications which use XID frames to test the 
physical link. 


TRXIDR calls: trans(XlDR, xIoc, xlen) 

See also the global error codes on page B.1-1. 


{■ 

printf ("\nResult from trxidr® =%cl\n", trxidr (•abcd*,4)); 

} 
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Sample Program 


There are three sample programs provided on the C Sample 
Programs Disk for the LAPD Library. These are: 

. • LAPDA.C 

• LAPDB.C 

• LAPDAB.C 
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LAPDA.C This program initializes the Chameleon’s Port A for layer 3 

transmission over a V-type interface. 


^include 

#include 

^include 

^define 


<stdio.h> 
<video.h> 
<cham.h> 
MOD128 1 


main () 

{ 

extern long _stdvt; 
extern unsigned int rxlen; 
int i, result, err; 

unsigned char rxbuf[100], txbufflOO], c; 


/••••••••••♦ SETUP PORT "A" 

if ( (err=setport(PORTA)) != 0 ) { 
printf( "ERROR: setport = Xd\n", err); 
exit{0); 

} 

puts(CLEARS) ; /• clear the screen •/ 
printf {"\n\n"); 


configure LAPO parameters & set link on */ 


printf ("XnResult 
printf ("XnResult 
printf ("XnResult 
printf ("XnResult 
printf ("XnResult 
printf ("XnResult 
printf ("XnResult 
printf ("XnResult 
printf ("XnResult 
printf ("XnResult 
printf ("XnResult 
printf ("XnResult 
printf ("XnResult 


from initpl == %d", initpl(DCE, NETWORK, NRZ, 96001 )); 

from setflg == %d" ,setflg(FILLFF)) ; 

from set_mod == Xd".set_mod (M00128)); 

from s_n200 == %d",s_n200 (3)); 

from s_n201 == %d",s_n201 (260)); 

from set_sapi == Xd",set_sapi (0)); 

from set_tei == %d",set_tei (10)); 

from s_t200 =* Xd",s_t200 (10)); 

from s_t203 == Xd",s^t203 (20)); 

from set_window == Xd" .set_window (3)); 

from set_sconfig == Xd" ,set_sconf ig (0x00)); 

from set_rntei == XdXn" ,set_rsapi (1,0)); 

from set_rntei == XdXn" ,set_rntei (1,10)); 
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while ((statusO) != 4) /♦ check for information transfer state •/ 

{ 

puts(HOME); /♦ move. cursor to the upper left corner of the screen ♦/ 
printf ("XnResult from status ==%d\n” ,status( ) ) ; 
if{(c-getch(_stdvt)) == ’Q’ || c == 'q') exit(O); 

} 


for( i*0;i<=26;i++) 

txbuf[i] = 66 + i; /♦ fill transmit buffer with upper case letters •/ 

puts(CLEARS); /♦ clear the screen ♦/ 

printf ("Nn press RETURN to transmitXn" ) ; 
getcharO; 

/♦ TRANSMIT OUT SOME DATA •/ 

resul t=transmit(txbuf , i ) ; /♦ transmit txbuf & get result ♦/ 
printf{"Xnresult=XdXn'* . result) ; /♦ result of transmit •/ 

printf(’*Xn waiting to receiveXn"); 

/• WAIT FOR THE INC0MMIN6 DATA •/ 
do { 

receive( rxbuf ) ; /• if rxlen=0 then no data was received ♦/ 
if ((c*getch{_stdvt)) == ’Q* 1| c 'q*) exit(6); 

} while (rxlen**0); 

printf ("Xnrxlen = XdXn**, rxlen); 

/♦ THIS FIRST BYTE FROM THE RECEIVE IS THE STATUS BYTE ♦/ 



printf ("XnThe status from the receive command = XxXn" , rxbuf [0]) ; 


for( i = l; i< rxlen ;i*»'+) 

printf{"Xc rxbuf [i]) ; /♦ print results of data transfer ♦/ 

printf ("Xn press RETURN to exit programXn" ) ; 
getcharO; 
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LAPDB.C This program initializes the Chameleon’s Port B for layer 3 

transmission over a V-type interface. 

In this program, set_t1, set_t2, set_n1 and set_n2 are 
alternate representations for, respectively, T200, T203, N200, 
and N203. 


^include 
^include 
#include 
#def ine 


<stdio. h> 
<video. h> 
<cha(n. h> 
M00128 1 


main () 

{ 

extern long _stdvt; 
extern unsigned int rxlen; 
int i, result, err; 

unsigned char rxbuf[100], txbuf[100], c; 


SETUP PORT "B" 

if ( (err*setport(PORTB)) != 0 ) { 
printf ("ERROR; setport = %d\n", err); 
exit{0); 

} 

puts(CLEARS) ; /• clear the screen •/ 
printf ("\n\n"); 


/ 


/ 


/* configure LAPO parameters & set link on */ 


printf 

printf 

printf 

printf 

printf 

printf 

printf 

printf 

printf 

printf 

printf 

printf 

printf 

printf 


("\nResult from 
("\nResult from 
("\nResult from 
{"\nResult from 
("\nResult from 
("\nResult from 
("XnResult from 
{"\nResult from 
{"\nResult from 
("\nResult from 
("\nResult from 
("\nResult from 
("\nResult from 
{"\nResult from 


initpl *= Xd",initpl(DTE, SUBSCRIBER, NRZ, 96001)); 

setflg == %d",setflg(FILLFF)); 

set_mod == %d",set_mod (MOD128)); 

set_n2 == Xd'*,set_n2 (3)); 

set^nl == Xd",set_nl (260)); 

set_sapi == Xd",set_sapi (0)); 

set^tei == Xd".set_tei (10)); 

set^tl == Xd".set_tl (10)); 

set_t2 == %d",set_t2 (20)); 

set_windo«i == Xd" ,set_i«iindow (3)); 

set_sconfig == Xd" , set^sconf ig (0x08)); 

set_rntei == Xd\n’*,set_rsapi (1,0)); 

set_rntei == XdXn" ,set_rntei (1,10)); 

slon ** Xd",slon ()); 
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while ((statusO) 1= 4) /♦ check for information transfer state ♦/ 

{ 

puts(HOME); /♦ move cursor to the upper left corner of the screen ♦/ 
printf (’*\nResult from status ^-XdXn^.statusO); 
if((c=getch(_stdvt)) == 'Q' He =* ’q*) { slof(); exit(O); } 
if ((status( ) )==0) 

{ 

printf ("Vn Link Not Establ ishedNo”) ; 
slof(); /♦ bring link down ♦/ 
exit(O); 

} 

} 

puts(CLEARS); 

printfC’Xn waiting to receiveXn” ) ; 


/• WAIT FOR THE INC0MMIN6 DATA ♦/ 
do { 

receive( rxbuf ) ; /• if rxlen=0 then no data was received •/ 
if((c=getch(_stdvt)) == ’Q’ \\ c == ’q') { slof(); exit(O); } 
} while (rxlen»*0); 

printf ("\nrxlen = XdXn**, rxlen); 


/• THIS FIRST BYTE FROM THE RECEIVE IS THE STATUS BYTE •/ 
printf ("\nThe status from the receive command = Ixyn** , rxbuf [0]) ; 
for( i = l; Krxlen; i++) 

printfC^Xc ** , rxbuf[i]) ; /♦ print results of data transfer ♦/ 


for( i=0; i<=25; i++) 

txbuf[13 = 97 + i; /• fill transmit buffer with lower case letters •/ 

printf ("\n press RETURN to transmitXn” ) ; 
getchar{ ) ; 

/• TRANSMIT OUT SOME DATA ♦/ 

resul t*transmit( txbuf , i ) ; /* transmit txbuf & get result */ 
printf ("Xnresult^XdXn”, result); /♦ result of transmit •/ 

slof(); /• bring link down •/ 

printf ("Xn press RETURN to exit programXn” ) ; 
getchar( ) ; 
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LAPDAB.C This program initializes the Chameleon for Dual Port layer 3 

transmission over a V-type interface. 

In this program, set_t1, set_t2, set_n1 and set_n2 are 
alternate representations for, respectively, T200, T203, N200, 
and N203. 

^include <stdio.h> 

^include <video.h> 

^include <chaai.h> 

^define M00128 1 

conf ig_lapd( ) 

( 

/♦ configure LAPD parameters & set link on ♦/ 

printf ("\nResult from setfig == Xd",setflg(FILLFF)); 
printf ("\nResult from set_mod == Xd",set_mod (M00128)); 
printf ("XnResult from set_n2 == Xd'*,set_n2 (3)); 
printf ("XnResult from set_nl == Xd^.set^nl (260)),* 
printf ("\nResult from set_sapi == Xd",set_sapi (0)); 

• printf ("\nResult from set_tei == Xd-.set^tei (10)); 
printf ("\nResult from set_tl == Xd",set_tl (10)); 
printf ("\nResult from set_t2 == Xd",set_t2 (20)); 
printf ("\nResult from set_window ** Xd",set_window (3)); 
printf ("\nResult from set_rntei =* Xd\n" ,set_rsapi (1,0)); 
printf ("XnResult from set_rntei == Xd\n",set_rntei (1,10)); 

} 

init_ports( ) 

unsigned int err; 

/•••••••••♦• SETUP PORT "A" 

if ( (errssetport(PORTA)) != 0 ) { 
printf ( "ERROR: setport = XdXn", err); 
exit(O) ; 

} 

printf("\nXs****^ PORT A •••••\nXs" . FYELLOW, FBLUE) ; 
printf ("XnPort ’A' initpl *= Xd" , initpl(0CE, NETWORK. NRZ, 96001 )) ; 
printf ("XnResult from set_sconfig == Xd" . set_sconf ig (0x00)); 
conf ig_lapd( ) ; 

printf ("XnXspress RETURN to continueXnXs" . FRED, FBLUE) ; 
getchar( ); 
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/••••••••••• SETUP PORT "B" •••••••••••/ 

if ( (err=setport(PORTB)) 1= 0 ) { 
printf( "ERROR: setport = %d\n", err); 
exit(O); 

} 

printf("\n%s**^** PORT B .FYELLOW.FBLUE) ; 

printf ("\nPort ’B* initpl , initpl(DTE , SUBSCRIBER, NRZ. 96001 )) ; 

printf ("\nResult from set_sconfig Xd" ,set_sconf ig (0x08)); 
config_lapd( ); 

printf ("\nXspress RETURN to continue\nXs" , FRED, FWHITE ) ; 
getchar( ) ; 


send_data( port, buf .count) 
unsigned char port, *buf, count; 

{ 

setport(port) ; /• select the port to use ♦/ 
printf{FRED); 

if(port) /♦ port A is 0 and port B is 1 •/ 
printf ("\nPress RETURN to transmit data from port-B to port-A\n"); 
else 

printf ("Press RETURN to transmit data from port-A to port-B\n"); 
printf (FWHITE); 

getcharO; /♦ ¥»ait for a carrage return •/ 
setport (port); /• select the port ♦/ 

/♦ TRANSMIT OUT SOME DATA •/ 

printf ( "Transmit result*Xd\n" ,transmit(buf, count) ) ;/♦ result of transmit ♦/ 


} 

wai t_f or_data( port ) 
unsigned char port; 

{ 

unsigned char c, i , rxbuf [ 100]; 
extern long _stdvt; 
extern unsigned int rxlen; 

setport(port); 

if (port) 

printf ("XsReceive: on port B\nXs" , FGREEN,FWHITE) ; 
else 

printf ("XsReceive: on port A\nXs" , FCYAN, FWHITE) ; 
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/• WAIT FOR THE INC0MMIN6 DATA •/ 
do { 

receive( rxbuf ) ; /• if rxlen=0 then no data was received ♦/ 
if((c=getch(_stdvt)) == ’Q’ || c == *q*) { slof{); exit{0); ) 

} while (rxlen-=0); 

printf ("rxlen = XdXn", rxlen); 

/♦ THIS FIRST BYTE FROM THE RECEIVE IS THE STATUS BYTE ♦/ 
printfCThe status from the receive command = %x\n" , rxbuf[0]) ; 
for( i*l; Krxlen; i++) 

printf("Xc ",rxbuf[i]); /• print results of data transfer •/ 

} 

main () 

{ 

extern long _stdvt; 
int i; 

unsigned char txbuf[100], c; 

/• INITIALIZE THE DUAL PORT CHAMELEON FOR LAPO •/ 

puts(CLEARS); /• clear the screen •/ 
init_ports( ) ; 

/• ESTABLISH A LINK BETWEEN THE PORTS (from port B) •/ 
printf ("\nResult from slon == Xd",slon ()); 

/• WAIT FOR LINK CONFIRMATION ♦/ 

while ((statusO) != 4) /♦ check for information transfer state •/ 

{ 

puts(CLEARS); 

puts{HOME); /• move cursor to the upper left corner of the screen ♦/ 
printf ("Result from status ==Xd\n" , status( ) ) ; 
if { (c*getch(_stdvt) ) == *Q' || c == ’q’) { slof(); exit(O); 
if ((status( ) )==0) 

{ 

printf ("\n Link Not Establ ishedXn" ) ; 
slof(); exit(O); 

} 
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/♦ SETUP THE DATA TO BE TRANSFERED, THEN SEND IT ♦/ 
for(i*0;i<=25;i++) 

txbuf[1] = 65 + i; /• fill transmit buffer with upper case letters •/ 
send_data( PORTA , txbuf , i ) ; 

/• WAIT TO RECEIVE THE DATA ON OPPOSITE PORT ♦/ 
wai t_f or_data( PORTS ) ; 

/• SETUP THE DATA TO BE TRANSFERED, THEN SEND IT •/ 
for(i=0;i<=25;i++) 

txbuf[i] =97+1; /• fill transmit buffer with lower case letters •/ 
send_data( PORTS , txbuf . i ) ; 

/• WAIT TO RECEIVE THE DATA ON OPPOSITE PORT ♦/ 
wa1t_for_data( PORTA) ; 
slof(); /* bring link down •/ 

prlntf ("\n%sPress RETURN to exit program\nXs",FRED,FWHITE) ; 
getctiarO; 
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B.4 AUTO HDLC SIMULATION C LIBRARY 


Introduction The HDLC Simulation C Library is called libhdic.a and is in the 

\lib directory. The Auto HDLC functions are listed in the table 
below so that you can locate them quickly within this section. 
Following the index, the functions are in alphabetical order with 
one function per page. 


FUNCTION 

PAGE 

INITP1 

B.4-2 

RECEIVE 

B.4-3 

SET_N1 

B.4-4 

SET_N2 

B.4-5 

SET__T1 

B.4-6 

SET__WINDOW 

B.4-7 

SLOP 

B.4-8 

SLON 

B.4.9 

STATUS 

B.4-10 

TRANSMIT 

B.4-1 1 


Also refer to Appendix B.1 for a description of common library 
functions and error codes. 

A sample program demonstrating the use of the HDLC library 
is provided at the end of this section. 
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INITP1 


Declaration 

int 

initpt (type! , type2, encode, bitrate) 


int 

type1; 


int 

type2; 


int 

encode; 


unsigned long bitrate; 


Range 

type1 

0 

DCE 

1 

DTE 



2 

ISDN 


type2 

0 

Network 


1 

Subscriber 


encode 

0 

NR2 



1 

NRZI 


bitrate 

SOL 

- 64000L 


Description This function initializes the Front End Processor and loads its 

simulation software. 


Returns 


0 Successful 
-1 Parameter error 
-2 P1 program file could not be loaded 
-3 Port is busy by the Analysis application (port should be 
off) 

See also the global error codes on page B.1-1. 
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RECEIVE 

Declaration 


Description 


Returns 


Example 


int recejve(packet) 
char ‘packet; 


This function receives an l-frame from P1 and places the l-field 
frame starting at the address pointed to by the passed variable 
^packet 

The external global variable rxlen will be set to the length of 
the received frame, if rxlen = 0, then no l-frame was received. 


0 Successful 

1 Link not established 

2 initpl not performed 

See also the global error codes on page 


do { 

receive (frame) ; 

} while (rxlen == 0); 
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SET_N1 

Declaration 


Range 


Returns 


Example 


int set n1(val) 

int val; 

val 1 - 512 


This function sets the value of N1 (the maximum size of a 
received frame in bytes). 


0 Successful 
-1 val outside of range 

See also the global error codes on page 


char RxBuf[128]; 
set_nl(sizeof (RxBuf )+2) ; 
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SET_N2 

Declaration 


Range 


Returns 


int set n2(val) 

int val; 


val 1 - 255 


This function sets the value of N2 (number of re- 
transmissions). 


0 Successful 
-1 vaJ outside of range 

See also the global error codes on page 
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SET T1 


Declaration 

Range 

Description 

Returns 


int set ^t1 (val) 

int val; 

val 1 - 255 seconds 


This function sets the value of the T1 frame level timer in units 
of seconds. 


0 Successful 
-1 va/ outside of range 

See also the global error codes on page 
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SET_WINDOW 

Declaration int set ^window(val) 

int val; 

Range val 1 -7 

Description This function sets the window size for the frame level. 

Returns 0 Successful 

-1 val outside of range 

See also the global error codes on page 
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SLOP 

Declaration int siof() 

Description This function disconnects the link at the frame level by sending 

a DISCONNECT. Be sure to check the link status for the 
result of this command. 

Returns See the global error codes on page B.1-1. 
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SLON 


Declaration 


Description 


Returns 


int slon{) 


This function attempts to establish a link at the frame level by 
sending a SABM. Verify that the link is established by using 
the status function before you transmit data. 


See the global error codes on page B.1-1. 
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STATUS 


Declaration 

Description 


Returns 


int statusO 


This function returns a value indicating the status of the frame 
level. 


0 Disconnected 

1 Link connection requested 

2 Frame reject state 

3 Link disconnection requested 

4 Information Transfer State 

5 Local Station Busy 

6 Remote Station busy 

7 Local and remote stations busy 

See also the global error codes on page 
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TRANSMIT 


Declaration 


Description 


Returns 


int transmit (packet, length) 
char ‘packet; 
int length; 


This function transmits an l-frame with the l-field set to the 
number of bytes specified by the passed variable length, 
starting at the address pointed to by the passed pointer 
*packet. 


0 Successful 

1 P1 busy (transmitting previous packet) 

2 initpl not performed 

3 Link not established 

See also the global error codes on page B.1-1. 
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Sample Programs There are three sample HDLC programs on the C Sample 

Program Disk. They are: 

• hdlca.c 

• hdicb.c 

• hdicab.c 


HDLCA.C This sample program demonstrates transmitting and receiving 

on Port A over a V.24 interface using the libhdic.a library. 

#1nc1ude <stdio.h> 

^include <video.h> 

#1nclude <cham.h> 

main( ) 

{ 

extern long _stdvt; 

extern unsigned int rxlen; /♦ global variable for receive data length ♦/ 

Int 1, result; 

unsigned char rxbuf[100],c; /♦ recleve frame data •/ 

/• SETUP PORT A •/ 

if ( {result*setport(PORTA)) != 0 ) { 
printf{ "ERROR: setport = Xd\n", result); 
ex1t(0); 

} 

/• INITIALIZE THE FRONT END PROCESSOR •/ 

if ( (result*initpl(DCE. NETWORK. NRZ. 96001)) != 0 ) { 
printf{"ERROR: initpl = Xd\n", result); 
exit(O); 

} 

/• CONFIGURE THE INPUT/OUTPUT ♦/ 

1f( {result*set_nl(512) ) ) pr1ntf( "ERROR: set_nl=Xd\n" , result) ; 

1f( (result=set_n2(5)) ) printf{ "ERROR: set_n2=Xd\n" , result) ; 

■if( (result=set_tl(255) ) ) printf( "ERROR: set_tl=Xd\n" , result) ; 

1f( ( result*set_tvindotii(2)) ) printf ("ERROR: set_window=Xd\n" , result) ; 
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/♦ WAIT FOR THE LINK •/ 

«iihile(status( ) I =4) /• ruait until link is up ♦/ 

{ 

puts(CL£ARS); 

printf ("1 ink status=%d\n" , status( ) ) ; 

if ( (c*getch(_stdvt)) *= *Q* || c == 'q') { slof(); exit(O); } /• fail safe •/ 

} 

printf("\nXsHit RETURN to send dataVnXs” .FRED,FWHITE); 
getchar(); 

/♦ SEND OUT SOME DATA •/ 

result=transniit("WXYZ" ,4) ; /♦ transmit ABCD & get result •/ 
printf("\nresult=Xd\n'*, result); /• result of transmit •/ 

printf ("\nWaiting to receive\n"); 


/♦ WAIT FOR SOME DATA FROM ANOTHER DEVICE •/ 
do { 

receive(rxbuf ); /* if rxlen>0 then no data was received */ 
if {{c*getch(_stdvt)) *Q* || c -* *q') { slof(); exit(O); } 

} while (rxlen**0); 


for(i=0;i<rxlen; i+-i-) 

printf{"Xx ",rxbuf[i]); /♦ print results of data transfer ♦/ 

printf ("\nXsHit RETURN to exit programXnXs" ,FRED,FWHITE) ; 
getcharO; 

slof(); /• bring link down ♦/ 


} 
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HDLCB.C This sample program demonstrates transmitting and receiving 

on Port B over a V.24 interface using the libhdic.a library. 

^include <std1o.h> 

^include <video.h> 

^include <chani.h> 

ma1n( ) 

{ 

extern long _stdvt; 

extern unsigned Int rxlen; /♦ global variable for receive data length ♦/ 
int i, result; 

unsigned char rxbuf[100],c; recieve frame data 

/• SETUP PORT B •/ 

if { (result=setport(PORTB)) != 0 ) { 
printf ("ERROR: setport = %d\n", result); 
exit(O); 

} 

/♦ INITIALIZE THE FRONT END PROCESSOR •/ 

if ( (result=initpl{DTE. SUBSCRIBER, NRZ, 96001)) !* 0 ) { 
printf ("ERROR: initpl * Xd\n", result); 
axit(O): 

} 

/• CONFIGURE THE INPUT/OUTPUT •/ 

if{ (result=set_nl(512) ) ) printf ("ERROR: set_nl=Xd\n" , result) ; 
if( (result*set_n2(5) ) ) printf ( "ERROR: set_n2=Xd\n" , resul t) ; 
if( (result*set_tl(255) ) ) printf ( "ERROR: set_tl-Xd\n", result) ; 
if( ( result*set_window{2) ) ) printf ("ERROR: set_tvindow=%d\n" , result) ; 

/• ESTABLISH A LINK ♦/ 
slon(); 
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/♦ WAIT FOR THE LINK ♦/ 

wh11e(status( ) ! =4) /• wait until link is up •/ 

{ 

puts(CLEARS) ; 

printf ("1 ink status=Xd\n" .status( ) ) ; 

if ((c=getch(_stdvt)) == *Q' || c == *q') { slof{); exit(O); } 
if (status( )==0) /• link cannot be established - exit routine •/ 
{ 

printf ( "\nLink has been disconnectedXn** ) ; 
slof(); exit(O); 

} 

} 

printf ( "\nWaiting to receiveXn"); 

/* WAIT FOR SOME DATA FROM ANOTHER DEVICE «/ 
do { 

receive(rxbuf ) ; if rxlen=0 then no data was received 
if ((c*getch(_stdvt)) *0* || c *- ‘q*) { slof(); exit(O); } 

} while (rxlen*s0); 

for( i»0; i<rxlen; 

printf("Xx ",rxbuf[i3); /• print results of data transfer 4/ 

printf{"\nXsHit RETURN to send dataXnXs" ,FRED,FWHITE); 
getcharO; 

/• SEND OUT SOME DATA •/ 

result=transniit{''ABCD**,4); /♦ transmit ABCD & get result •/ 
printf ('*\nresult=Xd\n" , result) ; /• result of transmit •/ 

printf ("\nXsHit RETURN to exit programXnXs" ,FRED, FWHITE) ; 
getcharO; 

slof(); /• bring link down •/ 


} 
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HDLCAB.C This sample program demonstrates transmitting and receiving 

on Dual Port machine over a V,24 interface using the libhdic.a 
library. 

^include <stdio.h> 

^include <video.h> 

^include <cham.h> 

confIgO 

{ 

int result; 
printf(FR£D); 

if{ ( result*set_nl(512) ) ) printf ("ERROR: set_nl=%d\n" , result) ; 
if{ ( result=set_n2(5)) ) printf ("ERROR: set_n2=%d\n** , result) ; 
if( ( result=set_tl(256)) ) printf ("ERROR: set_tl=%d\n" , result) ; 
if( ( result=set_window{2) ) ) printf ("ERROR: set_window=Xd\n" , result) ; 
printf(FWHITE); 


init_ports( ) 

{ 

int result; 

/• SETUP PORT A •/ 

printf ("XsSetting up PORT A\nXs",FGREEN.FWHITE); 

if ( (result*setport( PORTA)) !* 0 ) { 
printf ("ERROR: setport = Xd\n", result); 
exit(O); 

} 

if ^ ^r 0 SuU*initpl(DCE, NETWORK, NRZ, 96001)) != 0 ) { 
printf ("ERROR: initpl = XdSn”, result); 
exit(O); 

} 

configO; /• CONFIGURE THE PORT •/ 

/• SETUP PORT B •/ 

printf ("XsSetting up PORT B\nXs" ,FGREEN,FWHITE) ; 

if ( (result*setport(PORTB)) !* 0 ) { 
printf ("ERROR: setport = Xd\n", result); 
exit(O); 

} 
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if { (resuU=initpl(DTE, SUBSCRIBER, NRZ, 96001)) != 0 ) { 
printf ("ERROR: initpl = %d\n", result); 
exit(O); 

} 

configO; /• CONFIGURE THE PORT •/ 

} 

main() 

{ 

extern long _stdvt; 

extern unsigned int rxlen; /♦ global variable for receive data length ♦/ 
int i, result; 

unsigned char rxbuf[100] ,c,txbuf[25]; /• recieve frame data •/ 
puts(CLEARS); /• clear the screen ♦/ 


/• INITIALIZE THE FRONT END PROCESSORS •/ 
init_ports( ); 

/♦ ESTABLISH A LINK •/ 

slon(); /♦ since the last setport was t>0RTB, PORTS establishes the link •/ 

/♦ WAIT FOR THE LINK */ 


while( (result=status{ )!=4) ) /• wait until link is up •/ 

{ 

puts(CLEARS); 

printf ( "link status=Xd\n" , result); 

if ((c=getch(_stdvt)) == 'O' || c == 'q') {slof(); exit(O);}/* fail safe •/ 
if (status( )*=0) /• link cannot be established - exit routine ♦/ 

{ 

printf ( "\nLink has been disconnectedXn") ; 
slof(); exit(O); 

} 

} 

for(i=0;i<=24;i*M-) 

txbuf[i] = 33 + i; /♦ fill transmit buffer with characters ♦/ 

printf("\nXsHit RETURN to send data: PORTA to PORTBXnXs" , FYELLOW, FWHITE) ; 
getchar(); 

setport( PORTA); /♦ select the port to use •/ 


Tekelec 


B.4-17 


Version 2.4 





Chameleon 32 C Manual 


Appendix B.4: Auto HDLC Library 


/• SEND OUT SOME DATA •/ 

result*trwinsniit(txbuf ,25) ; /• transmit data & get result •/ 

printf{"Xs\nTransm1t result=Xd\nXs",FBLUE,result,FWHITE); /♦ result of transmit ♦/ 
setport(PORTB) ; /♦ select the port to use •/ 

/• WAIT FOR SOME DATA FROM PORTA •/ 
do { 

rece1ve(rxbuf ) ; /♦ If rxlen*0 then no data was received ♦/ 

If {(c=getch(_stdvt)) ** *Q' || c == *q*) { slof(); ex1t(0); } 

} while (rxlen==0); 

for( i=0;1<rxlen; 1++) 

printf("%c ",rxbuf[1]); /♦ print results of data transfer •/ 

pr1ntfC\nXsH1t RETURN to send data: PORTB to PORTA\nXs" , FYELLOW, FWHITE) ; 
getchar(); 

/• SEND OUT SOME DATA •/ 

result-transm1t(txbuf ,25); /* transmit data & get result ♦/ 

pr1ntf("Xs\nTransm1t result*Xd\nXs" ,FBLU£, result, FWHITE) ; /♦ result of transmit ♦/ 
setport(PORTA); /♦ select the port to use •/ 


/• WAIT FOR SOME DATA FROM PORTB ♦/ 
do { 

rece1ve(rxbuf ); /• If rxlen=0 then no data was received ♦/ 

If ({c*getch(_stdvt)) ** *Q* Me == *q*) { slof(); ex1t(0); } 
} while (rxlen*=0); 


for( 1=0; Krxlen; 1++) 

pr1ntf("Xc ",rxbuf[13); /• print results of data transfer •/ 

pr1ntf("\nXsH1t RETURN to exit program\nXs",FREO,FWHITE); 
getcharO; 

slof(); /• bring link down ♦/ 


} 
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B.5 SDLC SIMULATION C LIBRARY 


Introduction The SDLC Simulation C Library is valid for the SNA automatic 

frame level. It is called libsdic.a and is in the Mib directory. 
The functions are described in alphabetical order, one function 
per page, beginning on the following page. 


FUNCTION 

PAGE 

INITP1 

B.5-2 

RECEIVE 

B.5-3 

SET_ADR 

B.5-4 

SET__N2 

B.5-5 

SET_T1 

B.5-6 

SET_T2 

B.5-7 

SLOP 

B.5-8 

SLON 

B.5-9 

STATUS 

B.5-1 0 

TRANSMIT 

B.5-1 1 

TRNSl 

B.5-1 2 

TRSIFR 

B.5-1 3 

TRTST 

B.5-1 4 

TRUI 

B.5-1 5 

XID 

B.5-1 6 


Also refer to Appendix B.1 for a description of common library 
functions. 


Note N1 (maximum packet size in bytes) is set to 512 and cannot 

be changed. 

A sample program using the SDLC library is provided at the 
end of this section. 
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INITP1 


Declaration 


Range 


Description 


Returns 


int initpl (typel ,type2,encode,bitrate) 

int typel ; 

int type2; 

int encode; 

unsigned long bitrate; 


typel 

0 

DCE 

1 

DTE 


2 

ISDN 

type2 

0 

Primary 


1 

Secondary 

encode 

0 

NRZ 


1 

NRZI 

bitrate 

SOL 

- 64000L 


This function initializes the Front End Processor and loads its 
simulation software. 


0 Successful 
-1 Parameter error 

-2 Front End Processor simulation programs cannot be 
loaded 

See also the global error codes on page 
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RECEIVE 

Declaration 


Description 


Returns 


Example 


int receive(packet) 
char 'packet; 


This function receives an l-frame from P1 and places the l-field 
frame starting at the address pointed to by the passed variable 
^packet 

The external global variable rxlen will be set to the length of 
the received frame. If rxlen = 0, then no l-frame was received. 


0 Successful 

1 Link not established 

2 initpl not performed 

See also the global error codes on page B.1-1. 


do { 

receive (frame); 

} while (rxlen == 0); 
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SET ADR 


Declaration 


Range 

Description 


Returns 


int set adr(val) 

int val; 


vai 0 - 255 


This function sets the transmit and receive address. It should 
be used before transmitting or receiving frames. 


0 Successful 
-1 Parameter error 

See also the global error codes on page B.1-1. 
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SET_N2 

Declaration 

Range 


Returns 


int set n2(val) 

int val; 

val 1 - 255 


This function sets the value of N2 (number of re- 
transmissions). This function is available only if the 
Chameleon 32 is configured as a primary station. 


0 Successful 
-1 val outside of range 
5 Not configured as a primary station 

See also the global error codes on page B.1-1. 
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SET T1 


Declaration 


Range 

Description 


Returns 


int set_t1 (val) 
int val; 

val 1 - 255 seconds 


This function sets the value of the T1 frame level timer in units 
of seconds. This function is available only if the Chameleon 
32 is configured as a primary station. 


0 Successful 
-1 val outside of range 
5 Not configured as a primary station 

See also the global error codes on page B.1-1. 
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SET_T2 

Declaration 


Range 

Description 


Returns 


int set ^t2(val) 

int vai; 


val 0 - 255 seconds 


This function sets the value of the T2 frame level timer, which 
is the maximum number of seconds allowed between the 
transmission of frames. This function is valid only when the 
Chameleon is simulating a Primary station (see initpl). 


0 Successful 
-1 Error 

5 Not configured as a primary station 
See also the global error codes on page B.1-1 . 
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SLOP 


Declaration 

Description 


Returns 


int slof() 


This function disconnects the link at the frame level by sending 
a DISCONNECT. Be sure to check the link status for the 
result of this command. 


0 Successful 

5 Not configured as a primary station 
See also the global error codes on page B.1-1. 
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SLON 


Declaration 


Description 


Returns 


int slon() 


This function attempts to establish a link at the frame level by 
sending a SARM. This function is available only if the 
Chameleon 32 is configured as a primary station. Be sure to 
use STATUS to ascertain that the link is established before 
you use TRAN to transmit. 


0 Successful 

5 Not configured as a primary station 
See also the global error codes on page B.1-1. 
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STATUS 


Declaration 


Description 


Returns 


int statusO 


This function returns a value indicating the status of the frame 
level. 


If the Chameleon 32 is configured as a primary station, 
STATUS returns the following values: 

0 Normal Disconnected Mode 

1 Link Request State 

2 Disconnect Request State 

3 Information Transfer State 

4 Local Station Busy 

5 Remote station busy 

6 Local and remote stations busy 


If the Chameleon 32 is configured as a secondary station, 
STATUS returns the following values: 

0 Normal Disconnected Mode 

1 Initialization Mode 

2 Frame Reject Mode 

3 Information Transfer State 

4 Local Station Busy 

5 Remote Station busy 

6 Local and remote stations busy 

See also the global error codes on page B.1-1 . 
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TRANSMIT 


Declaration 


Description 


Returns 


transmit (packet.length) 
char 'packet; 
int length; 


This function transmits an l-frame with the l-field set to the 
number of bytes specified by the passed variable length, 
starting at the address pointed to by the passed pointer 
*packet. 


0 Successful 

1 P1 busy (transmitting previous packet) 

2 initpl not performed 

3 Link not established 

4 Length error (if length > 51 0) 

See also the global error codes on page B.1-1. 
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TRSIFR 


Declaration 


Description 


Returns 


trsifr (packet, length) 
char “packet; 
int length; 


This function transmits a sequenced l-frame with the l-field set 
to the number of bytes specified by the passed variable 
length, starting at the address pointed to by the passed 
pointer *packet. 


0 Successful 

1 P1 busy (transmitting previous packet) 

2 initpl not performed 

3 Link not established 

4 Length error (if length > 51 0) 

See also the global error codes on page 
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TRNSI 


Declaration 


Description 


Returns 


trnsi (packet, length) 
char "packet; 
int length; 


This function transmits a non-sequenced l-frame with the l-field 
set to the number of bytes specified by the passed variable 
length, starting at the address pointed to by the passed 
pointer *packet 


0 Successful 

1 PI busy (transmitting previous packet) 

2 initpl not performed 

3 Link not established 

4 Length error (if length > 51 0) 

See also the global error codes on page 
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TRTST 


Declaration 


Description 


Returns 


trtst (packet, length) 
char “packet; 
int length; 


This function transmits a test frame with the l-field set to the 
number of bytes specified by the passed variable length, 
starting at the address pointed to by the passed pointer 
jacket This function is valid only when the Chameleon is 
simulating a Primary station (see initpl). 


0 Successful 

1 PI busy (transmitting previous packet) 

2 initpl not performed 

3 Link not established 

4 Length error (if length >510) 

5 Not configured as a primary station 

See also the global error codes on page 
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TRUI 


Declaration 


Description 


Returns 


trui (packet, length) 
char ‘packet; 
int length; 


This function transmits an unnumbered l-frame with the l-field 
set to the number of bytes specified by the passed variable 
length, starting at the address pointed to by the passed 
pointer jacket. 


0 Successful 

1 P1 busy (transmitting previous packet) 

2 initpl not performed 

3 Link not established 

4 Length error (if length >510) 

See also the global error codes on page 
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XID 


Declaration 


Description 


Note 


Returns 


extern char ident[ ]; 7*6 bytes*/ 

int xid(); 


This function transmits an XID frame containing the data in the 
externally available character array ident[ ], starting at ident[1], 
if an XID command is received. This array will be used to 
transmit the XID response. 

This function can be used only when the link is in the Normal 
Disconnected mode (the link is not running). 


0 Successful 

1 P1 not initialized 

2 P1 fails to responds 

3 Not in normal response mode 

4 Illegal frame (if secondary) 

See also the global error codes on page B.1-1. 
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Sample Programs There are three sample SDLC programs on the C Sample 

Program Disk. They are: 

• sdica.c 

• sdicb.c 

• sdicab.c 


SDLCA.C This sample program demonstrates transmitting and receiving 

on Port A over a V.24 interface using the libsdic.a library. 

^include <stdio.h> 

^include <v1deo.h> 

#inc1ude <chaiii.h> 


main() 

{ 

extern long _stdvt; 

extern unsigned int rxlen; /• global variable for receive data length ♦/ 
int i, result; 

unsigned char rxbuf[100],c; /* receive frame data */ 

/• SETUP PORT A •/ 

if ( (result*setport( PORTA)) != 0 ) { 
printf( "ERROR: setport = %d\n", result); 
exit(O); 

} 



/• INITIALIZE THE FRONT END PROCESSOR ♦/ 

if ( (result=initpl(OCE, PRIMARY, NRZ, 96001)) 1= 0 ) { 
printf("ERROR: initpl = Xd\n", result); 
exit(O); 

} 

/• CONFIGURE THE INPUT/OUTPUT •/ 

set_adr(l); /• sets transmit & receive addresses •/ 
set_n2(10); /♦ set number of retransmissions to 10 •/ 
set_tl(4); /♦ set tl frame level timer to 4ms •/ 
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set_t2(40); /• set t2 frame level timer to 40 •/ 

/♦ ESTABLISH A LINK •/ 
slon( ); 

/• WAIT FOR THE LINK •/ 

while(status()!*3) /♦ wait until link is up •/ 

{ 

puts (CLEARS) : 

printfCstatus = Xd ",status()); 

if((c»getch(_stdvt)) == *0’ |1 c *= ’q') {slof(); exit(O):}/* fail safe •/ 

} 

for(;;) 

{ 

/• SEND OUT SOME DATA ♦/ 

printf ("\nXsSelect which type of transmit function to useXnXs" , FRE0,FWHITE) ; 
printf("\t 1. Transmit\n\t2 . TrsifrXn**); 
printf{"XsXt 3. EXIT THE PROGRAMXnXs" , FCYAN, FWHITE) ; 

while( (c*getcwt(_stdvt)-48) > 3 && c < 1 ) 

; /• wait for a valid choice ♦/ 

switch(c) 

{ 

case 1: 

result=transmit( "transmit" ,8) ; /♦ transmit data & get result •/ 
printf ("XsXnTransmit Result=XdXn%s" , FYELLOW, result, FWHITE) ; 
break; 
case 2: 

result=trsif r( "trsif r" ,6) ; /• transmit data & get result •/ 
printf ("XsXnTrsifr Result=XdXnXs" ,FYELL0W, result, FWHITE ) ; 
break; 
case 3: 
slof(); 
exit(O) ; 

} 

/• WAIT TO RECEIVE SOME DATA •/ 
printf ( "XnWaiting to receiveXn"); 

printf ( "XsPress *q' to return to the MENUXnXs" , FRED, FWHITE) ; 
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do{ 

recei ve( rxbuf ) ; /♦ if rxlen=0 then no data mas received •/ 
if ((c=getch(_stdvt)) == ’0’ || c == 'q*) break; /• fail safe ♦/ 
} mhile (rxlen==0); 

for( i=0; i<rxlen; i++) 

printf("%c ", rxbuf [i]) ; /♦ print results of data transfer ♦/ 

} /♦ end forever •/ 

} 
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SDLCB.C This sample program demonstrates transmitting and receiving 

on Port B over a V.24 interface using the libsdic.a library. 

} include <std1o.h> 

^include <v1deo.h> 

^Include <cha(n.h> 


(nain( ) 

{ 

extern long _stdvt; 

extern unsigned int rxlen; /• global variable for receive data length ♦/ 
int i , result; 

unsigned char rxbuf[100],c; /♦ receive frame data •/ 

/• SETUP PORT B ♦/ 

if { {result=setport(PORTB)) != 0 ) { 
printf( "ERROR: setport = %d\n", result); 
exit(O); 

} 

/♦ INITIALIZE THE FRONT END PROCESSOR */ 

if ( (result=initpl(DTE, SECONDARY, NR2, 96001)) != 0 ) { 
printf( "ERROR: initpl * Xd\n", result); 
ex1t(0); 

} 

/• CONFIGURE THE INPUT/OUTPUT •/ 

set_adr(l); /• sets transmit & receive addresses ♦/ 

/♦ WAIT FOR THE LINK •/ 

while(status( ) ! =3) /• wait until link is up ♦/ 

{ 

puts(CLEARS) ; 

printf( "status = Xd ",status()); 

if ({c«getch(_stdvt)) == *Q* || c == 'q') exit(O); /• fail safe •/ 

} 
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for(;;) 

{ 

/• WAIT TO RECIEVf SOME DATA •/ 
printf('*\nWaiting to recelveXn** ) ; 

printf("XsPress ’q' to return to the MENU\nXs“ . FRED, FWHITE) ; 
do 

{ 

receive( rxbuf ) ; /• if rxlen=0 then no data ¥fas received 
if((c=getch(_stdvt)) == *Q' 1| c == ’q*) break; /• fail safe •/ 

} while (rxlen==0); 

for( i*0; i<rxlen; i-*-**-) 

printf("Xc "*rxbuf[i]); /• print results of data transfer ♦/ 

/• SEND OUT SOME DATA •/ 

printf ( "\nXsSelect which type of transmit function to useVnXs" , FRED, FWHITE) ; 
printf("\t 1. Transmit\n\t2, Trsifr\n*); 
printf(“Xs\t 3. EXIT THE PROGRAM\nXs",FCYAN.FWHIT£); 

while( (c*getcwt(_stdvt)-48) > 3 && c < 1 ) 

; /• wait for a valid choice •/ 

switch(c) 

{ 

case 1: 

pesult*transniit( "transmit" ,8) ; /• transmit data & get result •/ 
printf ( -XsNnTransmi t Resul t=Xd\nXs" . FYELLOW, resul t , FWHITE ) ; 
break; 
case 2 : 

result=trsif r("trsif r** ,6) ; /• transmit data & get result •/ 
printf { "XsVnTrsif r Resul t=Xd\nXs", FYELLOW, resul t, FWHITE ) ; 
break; 
case 3: 
exit(O); 

} 

} /• end forever ♦/ 

} 
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SDLCAB.C This sample program demonstrates transmitting and receiving 

on a Dual Port machine over a V.24 interface using the 
libsdic.a library. 

#include <stdio.h> 

^include <video.h> 

^include <chain.h> 

lnit_ports( ) 

{ 

int result; 

/• SETUP PORT A •/ 

if ( (result=setport(PORTA)) !* 0 ) { 
printf( "ERROR; setport = Xd\n", result); 
ex1t(0) ; 

} 

/♦ INITIALIZE THE FRONT END PROCESSOR •/ 

if ( (resuU=initpl(DCE, PRIMARY. NRZ, 96001)) != 0 ) { 
printf ("ERROR: initpl - %d\n", result); 
exit(O); 

} 

/mmmmmmmmmmmmmmmm/ 

/• SETUP PORT B •/ 

if ( (result=setport(PORTB)) != 0 ) { 
printf( "ERROR: setport = Xd\n". result); 
exit(O); 

} 

/• INITIALIZE THE FRONT END PROCESSOR •/ 

if ( {resuU=initpl(DTE, SECONDARY, NRZ, 96001)) != 0 ) { 
printf ("ERROR; Initpl = Xd\n", result); 
exit(O); 

} 

} 
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send__data(port) 
unsigned char port; 

{ 

unsigned char c; 
int result; 

setport(port) ; /• select which port is active •/ 
if(port) 

printf( "SENDING FROM PORT B\n"); 
else 

printf( "SENDING FROM PORT A\n-); 

printf ( "\nXsSelect which transmit function to use. \n%s", FRED, FWHITE); 
printf("\t 1. Transroit\n\t2. TrsifrXn"); 
printf("%S\t 3. EXIT THE PROGRAM\nXs",FCYAN,FWHITE); 

while( (c*getcwt{_stdvt)-48) > 3 && c < 1 ) 

; /• wait for a valid choice ♦/ 

switch{c) 

{ 

case 1: 

result=transmit( "transmit" ,8) ; /• transmit data & get result •/ 
printf ("%s\nTransmit Result*%d\n%s", FYELLOW, result, FWHITE) ; 
break; 
case 2: 

result*trsif r("trsif r",6); /♦ transmit data & get result •/ 
printf ( "XsXnTrsif r Resul t=Xd\nXs" . FYELLOW, resul t , FWHITE ) ; 
break; 
case 3: 
slofO; 
exit(O); 

} 

} 

get_data(port) 
unsigned char port; 

{ 

unsigned char rxbuf[100],c; /• receive frame data •/ 

extern unsigned int rxlen; /* global variable for receive data length */ 
int i; 

setport(port); /♦ select which port is active •/ 
if (port) 

printf ("\n\nWai ting to receive on port B\n"); 
else 

printf {"\n\nWai ting to receive on port A\n"); 
printf ("XsPress 'q* to return to the MENUNnXs" , FRED,FWHITE) ; 
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do{ 

receive( rxbuf ) ; /♦ if rxlen=0 then no data was received •/ 
if ((c=getch(_stdvt) ) == 'Q* || c == *q*) break; /• fail safe ♦/ 

} while (rx en==0); 

for( i*0; i<rxlen; i++) 

printfCXc ",rxbuf[i3); /♦ print results of data transfer •/ 
printf ( “XnXn") ; 

} 

main( ) 

i 

unsigned char c; 

/• INITIALIZE BOTH PORTS •/ 
init_ports(); 

setport(PORTA); /• select which port is active ♦/ 

/• CONFIGURE THE INPUT/OUTPUT •/ 

set_adr(l); /• sets transmit & receive addresses •/ 
set_n2(10); /• set number of retransmissions to 10 ♦/ 
set_tl{4); /• set tl frame level timer to 4ms ♦/ 
set_t2(40); /♦ set t2 frame level timer to 40 •/ 

/• ESTABLISH A LINK •/ 
slon(); 

/• WAIT FOR THE LINK •/ 

while(status{ ) !>3) /• wait until link is up ♦/ 

{ 

puts (CLEARS) ; 

printf( "status = %d • " ,status( ) ) ; 

if((c=getch(_stdvt)) == ’Q' || c == 'q') {slof(); exit(O);)/^ fail safe •/ 
} 

for(;;) 

{ 

/• SEND OUT SOME DATA FROM PORT A ♦/ 
send_data( PORTA); 
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/• WAIT TO RECEIVE SOME DATA ON PORT B •/ 
get_data(PORTB); 

/• SEND OUT SOME DATA FROM PORT B •/ 
send_data(PORTB); 

/• WAIT TO RECEIVE SOME DATA ON PORT A •/ 
get_data( PORTA); 

} /• end forever •/ 

} 
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B.6 BASIC RATE INTERFACE LIBRARY 


Introduction The Basic Rate Library enables you to use the Chameleon 32 

ISDN Basic Rate Interface hardware with the C environment. 
The library is called libbri.a and is in the /lib directory. 

In general, your application should include BRI library routines 
which enable you to set up and modify the Basic Rate 
Interface from within your application. However, when you 
start a C application from the Applications Selection menu, you 
must set up the BRI before you can access the Applications 
Selection menu to start the application. This can be 
accomplished in two ways: 

• You can access the BRI Setup menu before starting the 
C application. This is done by pressing F7 PhysicI in the 
main configuration menu. 

• You can save the BRI Setup menu as part of the 
DEFAULT configuration file. The BRI is then 
automatically set up when the Chameleon is booted or 
reset. 

When the C application is then started, it uses the BRI Setup 
menu parameters. Your application can then use other 
routines to modify the setup or use BRI functions, as required 
by your test. If the application contains a BRI library setup 
routine, the application setup overrides the menu setup. 

When starting an application from the C Shell, if your 
application contains a valid BRI setup routine, it is not 
necessary to access the BRI Setup menu prior to starting your 
application. 

Chapter 3.1 describes he procedure for starting applications 
from the C Shell and from the Applications Selection menu 


Note You cannot use the C BRI library and the BASIC application at 

the same time. (The BASIC application enables the user to 
monitor and modify the BRI at run time.) The BASIC 
application is useful for Monitoring applications and non-C 
simulation applications, but results in an error message when 
used simultaneously with the C BRI library. The BASIC 
application is described in the Chameleon Protocol 
Interpretation Manual, Chapter 12. 


Tekelec 


B.6-1 


Version 2.5 





Chameleon 32 C Manual 


Appendix B.6: Basic Rate Interface Library 


The BRI functions are described on the following pages: 

FUNCTION PAGE 


Bas ^version B.6-2 

SetBasic B.6-3 


Also refer to Appendix B.1 for a description of common library 
functions and error codes. 

Several sample programs using the Basic Rate Interface 
library are provided at the end of this section. 
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Bas version 


Declaration 


Description 


char *Bas version{) 


This function returns a pointer to a string which indicates the 
date of the Basic Rate C Library version. 
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SetBasic 

Declaration 


Description 


int SetBasic(cmdblock, resbiock) 
int cmdblock [5]; 
int resbiock [5]; 

This function has two parameters blocks that are integer 
arrays. The minimum size currently needed is 4. 

The cmdblock (command block) parameter contains the input 
values needed. The first item in cmdblock (index 0) is the 
command. The arguments, if any, are given as subsequent 
entries in the table. 

The resbiock (result block) parameter is an array containing 
the results, if any, of the operation requested in the cmdblock. 

The first entry in the result block {resblock[0]) indicates if the 
command in cmdblock was completed successfully. The error 
code in resblockfOJ is the same for ail Basic Rate Library 
commands and is listed on the next page. Other values that 
are returned are given in subsequent result block elements, 
and are described with each command. 

When the requested operation cannot be done because of an 
existing selection, the currently selected values are returned. 


This is illustrated in the figure below; 


COMMAND 


RESULT 

Argument 1 


Result 1 

Argument 2 


Result 2 

etc. 


etc. 
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resblock[0] 
Error Codes 


The commands listed below are available as the first item in 
cmdblock. Note that the commands are different for Basic 
Rate Interface boards 0 and 1 to accomodate a dual port 
Chameleon 32 with two Basic Rate Interface boards installed. 

There are some hardware differences between board 0 and 
board 1. If you have only one Basic Rate Interface board 
installed on your Chameleon 32, you must use the commands 
that correspond to the board you are using. Generally, if you 
have only one Basic Rate interface board installed, it will be 
board 0. 


Board 0 

Board 1 

Command 

1 

101 

Setup 

2 

102 

Reactivate 

3 

103 

Reset 

4 

104 

Channel functions 

5 

105 

Signal functions 

6 

106 

Get status 

9 


Select trace option 

10 

110 

NT Power 

11 

111 

BRI Board Version 

12 

112 

Bit Inversion 

13 

113 

DTMF Tone Selection 

14 

114 

Generate DTMF Tone 


The commands are described on the following pages. 


The error codes for resblock[0J are the same for all Basic Rate 
Library commands and are listed below. 


Code 

Meaning 


00 

Successful 


01 

Hardware has already been set up 


02 

Requested function is not available 

for this 


configuration 


03 

Requested channel is invalid (for B1 , B2 and D) 

04 

Requested function is not available for this channel 

05 

Invalid command or request 


06 

DTMF tone position out of range 


07 

BRI parameters not set 


09 

BRI Menu is running (cannot access BRI 

from the 


BRI C library) 


10 

Basic Rate Interface board is not installed 
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cmdblock[0] = 1 
cmdblock[0] = 101 

Setup This command must be given before any other commands can 

be used. 


cmdblock[1] mode 1 Monitor 

2 Simulate NT 

3 Simulate TE 

resblock[0] See page B,6-4. 

resblock[lj Returns current mode, if unsuccessful 


cmdblock[0] = 2 
cmdbiock[0] = 102 

Reactivate This command reactivates the line. 


Argument None 
resblock[0] See page B.6-4. 


cmdbiock[0] = 3 
cmdblock[0] = 103 

Reset This command resets the current setup and BRI board. 


Argument None 
resbiock[0] See page B.6-4. 
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cmdblock[0] = 4 
cmdblockfo] - 104 
Channel 


Functions 

cmdblock[1] mode 

0 

Do not override current setup. 
Requested action is done only if 
it does not conflict with an 
existing selection. 



1 

Override current setup. If there 
is a conflicting setup, it is reset. 


cmdblock[2] channel 

1 

B1 channel 


2 

B2 channel 



3 

D channel 


cmdblock[3] selection 

1 

System 



2 

Milliwatt 



3 

Codec 



4 

External interface 



5 

Idle 


resblock[0] See page B.6-4. 


resblock[1 ] Channel as defined above (If resblock[0] * 0) 
resblpck[2] Selection as defined above (If resblock[0] * 0) 


cmdbiock[0] - 5 



cmdblock[0] = 105 

Signal Functions cmdblock[1] 

For NT 1 

Deactivate request 

2 

Send info-2 


3 

Send info-4 


4 

Activate NT 


5 

Reserved 


6 

Send single pulses 


7 

Send continuous pulses 


8 

Send info-2, test loop 2 


9 

Send info-4, test loop 2 


ForTE 1 

Deactivate 


2 

Activate at priority 8 


3 

Activate at priority 1 0 


4 

Activate TE 


5 

Reserved 


6 

Reserved 


7 

Reset PEB 2080 


8 

Send single pulses 


9 

Send continuous pulses 


10 

Activate test loop 3 


resblock[0] See page B.6-4. 
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cmdblk[0] = 
cmdblk[0] = 
Get Status 


6 

106 

Argument None 

resblock[0] See page B.6-4. 

resblock[1] Control byte received from PEB 2080. 

If Simulating an NT : 


resblock[2] 1 
2 

3 

4 

5 

6 

7 

8 


No clock signal 
Lost signal level 
Receiver not synchronous 
Error 

Info-1 received 
Receiver synchronized 
Deacitvation complete 
Undefined 


If Simulating a TE: 


resblock[2] 


1 Power up 

2 Deactivate request 

3 Slip detected 

4 Disconnected 

5 Error 

6 Resynchronizing 

7 Info-2 received 

8 Test mode 

9 Level received during test loop 

10 Info-4 received, D channel priority 8 or 9 

11 Info-4 received, D channel priority 10 or 
11 

12 Quiescent state 

13 Undefined 


If in Monitor mode: 


resblock[1] 

resblock[2] 

resblock[3] 


Control byte received from PEB 2080. 
same as resblock[2] from NT 
same as resblock[2] from TE 
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cmdblk[0] = 9 
Select Trace 
Option 


cmdbIkfO] = 10 
cmdbik[0] =110 
NT Power 


cmdbik[0] = 11 
cmdblk[0] =111 
Board Version 


cmdblk[0] = 12 
cmdblk[0] =112 
Bit Inversion 


This function is useful for debugging your programs. 

cmdblock[1] 0 Turns off the trace. 

1 Command/result display 

2 Detailed trace 

resblock[0] See page B.6-4 


This function enables you to specify the type of power 
provided from the NT to the TE. 

cmdblock[1] Mode 

1 Power source 1 under normal conditions 

2 Power source 1 under emergency 
conditions (reverses polarity) 

3 Power source 2 under normal conditions 

4 Power source 2 under emergency 
conditions (reverses polarity) 

5 Off (NT power lines are off) 


This function returns the version number of the BRI board, if 
available. 

resblock[0] See page B.6-4 

resblock[1 j BRI board version number 


This function inverts the data bits on the B-Channel. 

cmdblock[1] 1 Bit inversion on 

2 Bit inversion off 

resblock(0] See page B.6-4 
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cmdblk[0] = 13 
cmdblk[0] =113 
DTMF Tone 

Selection This is used in conjunction with Generate DTMF Tone (see 

below) to generate the Dual Tone Multi-Frequency tones when 
using Codec on a B-channel. This function sets up the DTMF 
tone array. You can select a maximum of 20 digits. The final 
digit must be zero. 

cmdblock[l] Position of the tone in the array. 
cmdblock[2i DTMF tone (valid ASCII digit) 

resblock[0] See page B.6-4 


cmdblk[0] = 14 
cmdbIkCO] =114 
Generate 

DTMF Tone This Is used in conjunction with the DTMF Tone Selection 

function to generate the Dual Tone Multi-Frequency tones 
when using Codec on a B-channel. This function dials the 
numbers in the DTMF tone array. 

resblock[0] See page B.6-4 
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Sample Programs There are three sample BRI programs on the C Sample 

Program Disk. They are: 

• bria.c 

• brib.c 

• briab.c 


BRIA.C This sample program demonstrates sending and receiving 

data on Port A using the BRI and the liblapd.c library. 

^include <stdio.h> 

^include <v1deo.h> 

^include <cham.h> 

#define M00128 1 

int resblock [5]; 
int cmdblock [5]; 

init_basic_rate( ) 

{ 


/♦ set basic rate to simulate NT ♦/ 

cmdblock[0] = 1; /♦ port A •/ • 

cmdb1ock[l] *2; /• NT type •/ 


SetBas i c( cmdbl ock , resb1 ock ) ; 
if( resblock[0] != 0 ) 

printf ("ERROR: result from SetBasic to NT = %d\n" , resblock[0]); 


/• set channel functions to D-channel ♦/ 


cmdblock[0] = 4; /♦ channel */ 

cmdblock[l] = 0; /• keep current setup •/ 

cmdblock[2] = 3; /• use D channel •/ 

cmdblock[3] = 1; /• system •/ 

SetBasic(cmdblock« resblock) ; 
if{ resblockfO] != 0 ) 

printf ("ERROR: result from SetBasic to D-Channel = %d\n" , resblock[0]) ; 


resetbasic( ) 

{ 

cmdblock[0]=3; /• reset current setup ♦/ 
SetBasic(cmdblock, resblock) ; 

} 
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ini t_lapd( ) 

( 

Int result; 

SETUP PORT •»A" 

if ( (result=setport(PORTA)) 0 ) { 
printf( "ERROR: setport = Xd\n" , resul t ) ; 
resetbasic( ) ; 
exit{0); 

} 

if( {result=initpl(ISDN, NETWORK, NRZ, 160001)) 1= 0) 
printf{ "ERROR: initpl = %d\n" , result ) ; 

/• configure LAPD parameters •/ 
if( (result=setflg(FILLFF)) != 0 ) 
printf( "result from setflag - %d\n" , result) ; 
if( ( result=set_net( )) != 0 ) 
printf ("ERROR: result from set_net = %d\n" , result) ; 
if( (result=set_mod {M00128)) !* 0 ) 
printf ("ERROR: result from set_mod == Xd\n" , result) ; 
if( (result=set_n2 (3)) != 0 ) 
printf ("ERROR: result from set_n2 %d\n" , result) ; 
if( (result*set_nl (260)) 0 ) 

.printf ("ERROR: result from set_nl %d\n" , result).; 
if( (result*set_sd0i (0)) 1= 0 ) 
printf ("ERROR: result from set_sapi ** Xd\n" , result); 
if( (result=set_tei (10)) != 0 ) 
printf ( "ERROR: result from set_tei ** %d\n" , result) ; 
if( (result^set.tl (10)) != 0 ) 

printf ( "ERROR: result from set_tl == %d\n" , result) ; 
if( (result*set.t2 (20)) != 0 ) 
printf ( "ERROR: result from set_t2 == %d\n" , resul t) ; 
if( ( result=set_windoi» (3)) != 0 ) 
printf ( "ERROR: result from set_window == %d\n" , result) ; 
if( ( resul t=set_rsapi (1,0)) != 0 ) 
printf ( "ERROR: result from set_rntei == %d\n" , result) ; 
if( (result=set_rntei (1,10)) != 0 ) 
printf ( "ERROR: result from set_rntei == i;d\n" , result) ; 
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main( ) 

r 

I 

unsigned char rxbuf[100], txbuf[30], c; 
extern unsigned int rx1en; 
int result, i; 
char frame [10]; 

for( i=0; i<10; i++) 


frame[i] = i +48; 

/• Initialize tha Basic Rate Interface ♦/ 
ini t_bas i c_rate( ) ; 

/• Initialize the Front End Processor (FEP) for LAPD •/ 
init_l apd( ) ; 

/* Wait for the link to come up ♦/ 


while ((status()) != 4) /♦ check for information transfer state ♦/ 

{ 

puts(CLEARS) ; 

printf ("NnResult from status s^XdXn" .status( )); 

if ((c=getch(_stdvt)) == ’Q' || c == *q') {slof(); resetbasic(); exit(O);} 

} 


/* Transmit a UI frame after the link is established •/ 
/♦ to see if their is a fixed TEI value . •/ 

printf ( "\nPress RETURN to transmit a UI frameXn**); 
getchar(); 

if( (result=trans(UI, frame, 10)) != 0 ) 


printf ( "Result from the UI transmit = %d\n** , result) ; 

/* transmit data ♦/ 

for( i=0; i<=25; i++) /♦ upper case letters •/ 

txbuf[i] = i +66; 

printf ("XnPress RETURN to send data from port A\n"); 
getchar(); 

if{ (result=transmit(txbuf , i )) != 0 ) /♦ transmit data & get result •/ 
printf ("TRANSMIT ERROR: resul t=%d\n" . resul t) ; 
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/♦ receive data ♦/ 

printf ( "\nWaiting to receive data on port A\n"); 
do { 

receive( rxbuf ) ; /• if rxlen*0 then no data was received ♦/ 
if((c*getch{_stdvt)) == 'Q' |1 c ** ’q’) {slof(); resetbasic( ) ; exit(O);} 
} while (rxlen»*0); 

if(rxlen != 0) 

'printf ( "\nReceive status = Xd\n" . rxbuf [0] ) ; 
for( i = l; i<rxlen; 

printf("%c ",rxbuf[i]); /• print results of data transfer •/ 

slof(); /• bring link down ♦/ 
resetbasic( ) ; 

printf ( "\nPress RETURN to end the programXn"); 
getchar( ); 
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BRIB.C This sample program demonstrates sending and receiving 

data on Port B using the BRl and the liblapd.c library. 


A^include <stdio.h> 
/^include <video.h> 
/^include <cham.h> 

jl^define M00128 1 

int resblock [5]; 
int crndblock [5]; 

in i t_basic_rate( ) 

{ 


/♦ set basic rate to simulate TE •/ 

cmdb1ock[0] = 101; /• port B •/ 
cmdblock[l] = 3; /• TE type •/ 

SetBasic( cmdbl ock , resblock ) ; 
if( resblock [03 != 0 ) 

printf( "ERROR: result from SetBasic to NT = %d\n",resblock[03); 

/♦ set channel functions to D-channel ♦/ 

cmdblock[03 =104; /♦ channel •/ 

cmdblock[l3 =0; /♦ keep current setup •/ 

cmdblock[23 = 3; /• use D channel •/ 

cmdblock[33 =1; /• system •/ 

SetBasic(cmdblock, resblock) ; 

if( resblock [03 != 0 ) 

printf( "ERROR: result from SetBasic to D-Channel = Xd\n" , resblock[03) ; 


resetbasic( ) 

{ 

cmdblock[03=103; /• reset current setup •/ 
SetBasic(cmdblock, resblock) ; 
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ini t_1apd( ) 
{ ' ~ 

int result; 


SETUP PORT -B” ♦•»••••••••/ 

if ( { result*setport(PORTB) ) != 0 ) { 
printf ("ERROR: setport = XdVn" , resul t) ; 
resetbasic{ ) ; 
exi t(0) ; 

} 

if( (result=initpl(ISDN,SUBSCRIBER»NRZ, 160001)) != 0) 
printf( "ERROR: initpl = %d\n" , result) ; 

/* configure LAPO parameters •/ 
if( (resuU=setf1g(FILLFF)) »= 0 ) 

printf("result from setflag = %d\n" , result) ; 
if( {result=set_mod (MOD128)) != 0 ) 
printf{ "ERROR; result from set_mod == %d\n" , result) ; 
if{ (result=set_n2 (3)) != 0 ) 
printf( "ERROR: result from set_n2 *= %d\n" , result) ; 
if( (result=set_nl (260)) != 0 ) 
printf ("ERROR: result from set_nl == %d\n" , resul t) ; 
if( (result=set_sapi (0)) t= 0 ) 
printf ("ERROR: result from set_sapi ==Xd\n’', result); 
lf( {result=set_tei (10)) != 0 ) 
printf ("ERROR: result from set_tei == %d\n" , result) ; 
if{ (result-set_tl (10)) !* 0 ) 
printf ("ERROR: result from set^tl == %d\n" , result); 
if( (result=set_t2 (20)) !* 0 ) 
printf ( "ERROR: result from set_t2 == %d\n" . result) ; 
if( (result=set_window (3)) != 0 ) 
printf ( "ERROR: result from set_windo» == %d\n" , result) ; 
if( ( result*set_rsapi (1,0)) != 0 ) 
printf ( "ERROR: result from set^rntei == %d\n" , result) ; 
if( ( result*set_rntei (1,10)) != 0 ) 
printf ("ERROR: result from set_rntei == %d\n" , result) ; 

} 

ina1n() 

{ 

unsigned char rxbuf[100], txbuf[30], c; 
extern unsigned int rxlen; 
int result, i,j; 

/♦ Initialize the Basic Rate Interface ♦/ 
init_basic_rate( ) ; 
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1 * Initialize the Front End Processor (FEP) for LAPO ♦/ 
init_lapd( ) ; 

/♦ establish information transfer state •/ 

if( ( result=slon( )) != 0 ) 
printf( "result from slon() = %d\n" , resul t ) ; 



/♦ Wait for the link to come up •/ 

while ((statusO) != 4) /♦ check for information transfer state ♦/ 

{ 

puts{CLEARS); 

printf ("\nResult from status ==%d\n" ,status( ) ) ; 

if((c=getch( stdvt)) == ’Q' j | c == 'q*) {slof(); resetbasic( ) ; exit(O);} 

} 

for(j=0;j<2;j++) { 

/• receive data •/ 

printf ( "\nWaiting to receive data on port BXn"); 

.do { 

receive( rxbuf ) ; /♦ if rxleri*0 then no data was received •/ 
if((c=getch(_stdvt)) *= *Q* || c *q*) {slof{); resetbasic( ) ; exit(O);} 
} while (rxlen*aO); 

if(rxlen != 0) 

printf ( "\nReceive status = %d\n" , rxbuf [0] ) ; 


for( i=l; i<rxlen; i++) 

printf{"%c ", rxbuf [i]) ; /• print results of data transfer •/ 

} 


/♦ transmit data •/ 

for( i=0; i<=25; i++) /♦ lower case letters •/ 

txbuf[i] = i 97; 

printf ( "\nPress RETURN to send data from port avn**); 
getchar( ) ; 

if( ( result=transroit( txbuf , i ) ) != 0 ) /♦ transmit data & get result •/ 
printf { "TRANSMIT ERROR: result=%d\n" , result) ; 

resetbasic( ) ; 

printf ( "\nPress RETURN to end the programVn"); 
getchar( ) ; 


} 
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BRIAB.C This sample program demonstrates sending and receiving 

data using a Dual Port Machine with the BRI and the liblapd.c 
library. 


/^include <stdio.h> 
^include <video*h> 
/(^include <chain.h> 
/(^define M00128 1 


int cmdblocic [5], resblock [5]; 
int result; 

Ini t_basic_rate( ) 

{ 

/• set port A to simulate MT •/ 

Cfndblock[0] = 1; /• port A */ 

cindblock[l] = 2; /• NT type •/ 

SetBasic(cmdblock,resblock) ; 
if( resblockCO] 1= 0 ) 

priiitf( "ERROR: result from SetBasic to NT = %d\n" , resblock[03) ; 


/• set channel functions to D-channel ♦/ 


cmdblock[0] * 4; /♦ channel ♦/ 

cmdblock[i] * 0; /• keep current setup ♦/ 

cmdblock[2] * 3; /• use 0 channel •/ 

cmdblock[3] =1; /• system •/ 

SetBasic(cnidblock, resblock) ; 
if( resblock[0] != 0 ) 

printf( "ERROR: result from SetBasic to 0-Channel = Xd\n" , resblock[0]) ; 

/♦ set port B to simulate TE •/ 

cmdblock[0] = 101; /• port B •/ 
cmdblock[l] = 3; /♦ TE type ♦/ 

SetBasic(cmdblock, resblock) ; 
if( resblock[0] != 0 ) 

printf( "ERROR: result from SetBasic to NT = Xd\n" , resblock[0]) ; 
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/♦ set channel functions to D-channel •/ 


cmdblock[0] = 104; /♦ channel ♦/ 

cmdbloc»c[l] = 0; /• keep current setup ♦/ 

cmdblock[2] = 3; /♦ use 0 channel •/ 

cmdblock[3] =1; /• system •/ 

SetBasic(cmdblock, resblock) : 
if( resblock [03 != 0 ) 

printf ("ERROR: result from SetBasic to D-Channel = %d\n" , resblock[03) ; 


resetbasicO 

{ 

cmdblock[03=3; /• reset port A's current setup ♦/ 
SetBasic(cmdblock, resblock) ; 

crodblock[03=103; /• reset port B’s current setup ♦/ 
SetBas1c(cmdblock, resblock) ; 

) 

conf ig_1 apd( ) 

{ 

/♦ configure LAPD parameters •/ 

if( (resuU=setflg(FILLFF)) != 0 ) 
printf("resul t from setflag = Xd\n" .result); 
if( (result*set_mod (M00128)) 1=0) 
printf{ "ERROR: result from set^oiod == %d\n" .result) ; 
if( (result=set_n2 (3)) 1=0 ) 
printf ("ERROR: result from set_n2 == %d\n" , result) ; 
if( (result=set^nl (260)) != 0 ) 
printf ("ERROR: result from set_nl == %d\n" . result) ; 
if( ( result=set_sapi (0)) != 0 ) 
printf ( "ERROR: result from set_sapi == ld\n" , result) ; 
if( (result=set_tei (10)) != 0 ) 
printf ("ERROR; result from set_tei == %d\n“ , result) ; 
if( (result=set_tl (10)) 1= 0 ) 
printf ( "ERROR: result from set_tl == %d\n" , result) ; 
if( ( result=set_t2 (20)) != 0 ) 
printf("ERROR: result from set_t2 == %d\n" , result) ; 
if( ( result=set_window (3)) != 0 ) 

printf ( "ERROR; result from set^window == %d\n" , result ) ; 
if( ( resul t=set_rsapi (1,0)) != 0 ) 
printf ( "ERROR: result from set_rntei == Xd\n" , resul t ) ; 
if( ( result=set_rntei (1,10)) != 0 ) 
printf ( "ERROR: result from set_rntei == Xd\n” , result) ; 
if( (result = set_sub()) !=0) 
printf ("ERROR: result from set_sub == %d\n" , resul t) ; 
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init_lapd( ) 

{ 

SETUP PORT "A" 

if ( (result=setport(PORTA)) != 0 ) { 
printf( "ERROR: setport = %d\n" , result) ; 
resetbasic( ) ; 
ex1t(0) ; 

} 

if( (result=initpl(ISON, NETWORK, NRZ, 160001)) != 0) 
printf( "ERROR; initpl = Xd\n" , result) ; 

if( (result=sset_net( )) != 0 ) 
printf( "ERROR: result from set_net = Xd\n" , result) ; 

conf ig_lapd( ) ; 

SETUP PORT "B" 

if ( (result*setport(PORTB)) != 0 ) { 
printf ("ERROR: setport = Xd\n" , result) ; 
resetbasic( ) ; 
exit(O); 

} 

if( (result=initpl{ISDN. SUBSCRIBER. NRZ, 160001)) 0) 

printf ( "ERROR: initpl * Xd\n" , result) ; 

conf ig_lapd( ); 


send_data(port,buf .buf^size) 
unsigned char port, ♦buf; 
int buf_size; 

{ 

setport(port) ; /• select which port to use ♦/ 

if(port) 

printf ( "\n\n\nPress RETURN to send data from port B\n"); 
else 

printf ( "\n\n\nPress RETURN to send data from port A\n"); 
getchar( ) ; 

puts(CLEARS) ; /• clear the screen •/ 

if( ( result=transmit(buf ,buf_size) ) !* 0 )/• transmit data & get result ♦/ 
printf ("TRANSMIT ERROR: result=Xd\n" , result) ; 
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get_data(port) 
unsigned char port; 

{ 

unsigned char rxbuf[100]. c; 
extern unsigned int rxlen; 
int i ; 

setport(port) ; /♦ select which port to use •/ 

if (port) 

printf ("NnOata received on port B:\n'*); 
else 

printf ("\nData received on port A:\n”); 
do { 

receive( rxbuf ) ; /• if rxlen=0 then no data was received •/ 
if((c=getch(_stdvt)) == ’Q’ || c == *q‘) {slof(); resetbasic{ ) ; exit{0);} 
} while (rxlen==0); 

if(rxlen != 0) 

printf ("XnReceive status = %d\n" , rxbuf[0]) ; 
for( i = l; iCrxlen; i -»--»■) 

printf("%c " ,rxbuf[i]) ; /• print results of data transfer ♦/ 

} 

niain( ) 

{ 

unsigned char txbuf[30], c; 
int i; 

char frame [10]; 

for( i=0; i<10; i++) /• setup the data for the UI frame, ascii 0 - 9 •/ 
frarae[i] = i +48; 


/♦ Initialize the Basic Rate Interface •/ 
init_basic__rate( ); 

/• Initialize the Front End Processor (FEP) for LAPD •/ 
init_lapd( ) ; 

/• The subscriber establishs the information transfer state •/ 
if{ { resul t=slon( ) ) != 0 ) 


printf ("result from slon() = %d\n" , result) ; 
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/♦ Wait for the link to come up •/ 

while {(statusO) != 4) /• check for information transfer state •/ 

{ 

puts(CL£ARS) ; 

printf (**\nResult from status s^XdXn" ,status{ ) ) ; 

if{(c®getch(_stdvt)) =* 'Q* 1| c ** 'q') {slof(); resetbasic( ) ; exit(O);} 

} 

/♦ Transmit a UI frame after the link is established •/ 

/• from port A to port B. ♦/ 

printf ("\nPress RETURN to transmit a UI frame from port ^\n"); 
getchar(); 

setport( PORTA) ; 

if( (result*trans(UI, frame, 10)) !* 0 ) 
printf ("Result from the UI transmit = lid\n" , result) ; 

get_data{PORTB) ; /• Receive the UI Frame on port B ♦/ 

/• Transmit data from port A to port 8 ♦/ 

for(i*0;i<»25;i++) /• upper case letters ♦/ 

txbuf[i] * i + 66; 

send_data( PORTA , txbuf , i ) ; 

get_data(PORTB) ; /♦ receive data on port B ♦/ 

/♦ Transmit data from port B to port A •/ 

for(i=0;i<=25;i++) /• lower case letters ♦/ 

txbuf [i] * i + 97; 

send_data( PORTS , txbuf , i ) ; 

get_data( PORTA) ; /• receive data on port A •/ 

slof(); /• bring link down •/ 
resetbasic( ) ; 

printf ( "\n\n\nPress RETURN to end the programXn"); 
getchar( ) ; 
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B.7 BSC C LIBRARY 


Introduction The BSC C Library (libbsc.a) is valid for IBM’s Binary 

Synchronous Communications protocol. It is in the \lib 
directory. 

The functions are described on the following pages: 


FUNCTION PAGE 


IDLE_MODE B.7-2 

INITP1 B.7-3 

RECEIVE B.7-4 

TRANSMIT B.7-5 

TREADY B.7-6 


Also refer to Appendix B.1 for a description of common 
library functions and error codes. 


A sample program using the BSC library is provided at 
the end of this section. 
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IDLE MODE 


Declaration 


Range 

Description 

Returns 


#include <cham.h> 
int Idle mode(mode) 
int mode; 


mode IDLE or 0 Transmits the idle character (FF) 
SYNC or 1 Transmits the SYN character 


This function specifies the character to be transmitted while 
the line is idle. 


0 Successful 

See also the global error codes on page B.1-1. 
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INITP1 

Declaration 

Range 


Description 

Returns 


int initpl (type, encode, bitrate, crc, data) 
int type; 

struct BSC CTRL encode; 
unsigned long bitrate; 
int crc; 
int data; 


type 0 DCE 
1 DTE 

encode This is a structure that defines the control 
characters for the BSC protocol. It is defined as 
follows: 

struct BSC CTRL 

< . Tu 

unsigned char eot; 

unsigned char syn; 

unsigned char die; 

unsigned char stx; 

unsigned char etx; 

unsigned char soh; 

unsigned char etb; 

unsigned char itb; 

unsigned char enq; 

}; 


bitrate 

50L- 

64000L 

crc 

0 

CRC1 6 block check algorithm 


1 

CCITT-CRC block check algorithm 

data 

0x10 

EBCDIC data 


0x04 

ASCII data (no parity) 


0X01 

ASCII data (even parity) 


0x00 

ASCII data (odd parity) 


This function initializes P1 and loads its simulation software. 


0 Successful 

-1 One or more parameter errors 

-2 Front End Processor program could not be loaded 

See also the global error codes on page B.1-1. 
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RECEIVE 


Declaration 


Description 


Returns 


Example 


int receive(frame) 
char “frame; 


This function receives a frame from PI and places the frame 
starting at the address pointed to by the passed variable 
frame. 

The external global variable rxlen is set to the length of the 
received frame. If rxlen = 0, then no frame was received. 


0 Good BCC or no frame waiting 

1 Bad BCC 

2 initpl not performed 

3 Overflow 

See also the global error codes on page B.1-1. 


• • • 
do { 

receive( frame) ; 

} while (rxlen == 0); 
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TRANSMIT 


Declaration int transmit(mode, frame, length) 

int mode; 
char “frame; 
int length; 


Description This function transmits the number of bytes specified by the 

passed variable length, starting at the address pointed to by 
the passed pointer Jrame, with the control characters and 
block check as specified by the passed value mode. The 
mode parameter is defined as follows: 


Start Framing Character 
0 = SOH 
1=STX 

End Framing Character 
00 = EOT 
01=ETB 
10 = ETX 
11= Illegal 

Transparent Text Enable 

0 = Normal Text 

1 = Transparent Text 

Transparent Mode 

0 = Transparent mode 0 (no OLE insertion) 

1 = Transparent mode 1 (DLE insertion) 

Text Mode 

0 = Control Mode 

1 = Text Mode 

Block Check Character (BCC) 

0 = Good BCC 

1 = Bad BCC 

Reserved (must be i ) 


Returns 0 Successful 

1 P1 busy (transmitting previous frame) 

2 initpl not performed 

3 Parameter error 

4 Buffer overflow 

See also the global error codes on page B.1-1 
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TREADY 

Declaration 


Description 


Returns 


int treadyO 


This function returns the status of the Front End Processor 
transmitter. 


0 Transmitter is ready for next frame 

1 Transmitter is busy (sending previous frame) 

2 initpl not performed 

3 Overflow 

See also the global error codes on page B.1-1 
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Sample Programs There are three sample BSC programs on the C Sample 


Program Disk. They are: 

# 

bsca.c 

• 

bscb.c 

# 

bscab.c 


BSCA.C This sample program demonstrates transmitting and receiving 

on Port A over a V.24 interface using the libbsc.a library. 

^include <stdio.h> 

#inc1ude <chain.h> 

^include <video.h> 
struct BSC_CTRL; 

aiain( ) 

{ 

char ch,crc; 

struct BSC_CTRL encode; 

extern unsigned int rxlen; /♦ global variable for receive data length •/ 
unsigned char atrans[100],rxbuf[128]; /• transmit & revieve arrays ♦/ 


int result, i; 



encode. eot 

s 

55 

encode. syn 

s 

50 

encode. die 

s 

16 

encode. stx 

s 

02 

encode. etx 

= 

03 

encode. soh 

z 

01 

encode. etb 

= 

38 

encode. itb 

= 

31 

encode. enq 

= 

45 


/• SET THE ACTIVE PORT TO "A* •/ 

if( ( result=setport( PORTA) ) 1= 0 ) { 

printf ("ERROR: setport = %d\n", result); 
exit(O) ; 

} 

/• INITIALIZE THE FRONT END PROCESSOR •/ 

if( (result=initpl(DCE,&encode.eot, 96001, CCITT,ASCII_EVEN_DATA)) ) { 
printf ("ERROR; initpl = Xd\n", result); 
exit(O) ; 

} 
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for ( i*0; i<=99; i++) 

atrans[i]=0x66; /♦ store hex 66 into transmit array •/ 

/♦ WAIT UNITL THE SYSTEM IS READY TO TRANSMIT •/ 

while( (tready( ))l*0) { /• loop while transmitter not ready ♦/ 

puts(CLEARS) ; /• clear screen ♦/ 

printf( "PRESS ANY KEY TO ABORT \n"); 
printf("TR£AOY STATUS *Xd\n" ,tready( )); 

1f((ch * getch (_stdvt)) != -1) /♦ check for key pressed •/ 

ex1t(0); 

} 

/• SEND OUT SOME DATA •/ 

printf("\n hit RETURN to send the data out of port 'A‘\n"); 
getcharO; 

resul t-transmit( 0x80, atrans, 100); /* transmit 100 hex 66 & get result */ 
printf("\nRESULT OF TRANSMIT=Xd\n- , result) ; 

/♦ WAIT FOR SOME DATA FROM THE OTHER DEVICE •/ 
printf ("NnWaiting to receiveXn"); 
do { 

rece1ve( rxbuf ); /* if rxlen«0 then no data was received */ 

} while (rxlen=«0); 

for( i*0; i<rxlen; i++) 

printf ( "%d)=%x " , i ,rxbuf[i]) ; /• print results of data transfer •/ 

printf ("\nPress RETURN to exit the program\n"); 
getcharO ; 


} 
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BSCB.C 


This sample program demonstrates transmitting and receiving 
on Port B over a V.24 interface using the libbsc.a library. 


#include <stdio.h> 

^include <cham.h> 

^include <video.h> 
struct BSC_CTRL; 

inain( ) 

{ 

char ch,crc; 

struct BSC_CTRL encode; 

extern unsigned int rxlen; /* global variable for receive data length 
unsigned char atrans[100], rxbuf[128]; /• transmit & revieve arrays •/ 
int result, i; 


encode. eot = 55 
encode. syn • 50 
encode. die • 16 
encode. stx » 02 
encode. etx = 03 
encode. soh - 01 
encode. etb » 38 
encode. itb = 31 
encode. enq » 45 


/• SET THE ACTIVE PORT TO *B" •/ 

if( ( result-setport( PORTS) ) != 0 ) { 
printf( "ERROR: setport = Xd\n", result); 
exit(O); 

} 

/• INITIALIZE THE FRONT END PROCESSOR •/ 

if( (result=initpl{DTE,&encode. eot, 96001, CCITT,ASCII_EVEN_OATA)) ) { 
printf{ "ERROR; initpl = %d\n", result); 
exit(O); 

} 

for (i=0;i<=99;i++) 

atrans[i]=0x22; /♦ store hex 22 into transmit array •/ 
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/♦ WAIT UNITL THE SYSTEM IS READY TO TRANSMIT •/ 

while((tready( ))!=0) { /♦ loop while transmitter not ready •/ 


puts(CL£ARS); /• clear screen ♦/ 
printf("PRESS ANY KEY TO ABORT \n"); 
printf(-TREAOY STATUS =%d\n" , tready( ) ) ; 

if((ch » getch {_stdvt)) != -1) /♦ check for key pressed •/ 

ex1t(0); 

} 

/♦ WAIT FOR SOME DATA FROM THE OTHER DEVICE •/ 
printf ("\nWaiting to receiveXn"); 
do { 

receive( rxbuf ); /• if rxlen=0 then no data was received •/ 

} while (rxlen*=0); 

for( i=0;i<rxlen ; i++) 

printf ('*!td)*5tx ",i,rxbuf[i]); /• print results of data transfer •/ 

/• SEND OUT SOME DATA •/ 

printf ("Xn hit RETURN to send the data out of port 'B'Xn**); 
getchar( ) ; 

result>transfflit(0x80,atrans,100); /♦ transmit 100 hex 22 & get result ♦/ 
printf ("XnRESULT OF TRANSMIT=XdXn" . result) ; 

printf ( "XnPress RETURN to exit the programXn"); 
getcharO; 


} 
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BSCAB.C This sample program demonstrates transmitting and receiving 

on a Dual Port machine over a V.24 interface using the 
libbsc.a library. 

^include <stdio.h> 

^include <cha(n.h> 

^include <video.h> 
struct BSC_CTRL; 

/• 

• SETUP BOTH OF THE PORTS 

♦/ 

init_ports() 

{ 

struct BSC_CTRL encode; 
int result; 

encode. eot 
encode. syn 
encode. die 
encode. stx 
encode. etx 
encode. soh 
encode. etb 
encode. itb 
encode. enq 

/• SET THE ACTIVE PORT TO "A" ♦/ 

if( ( result=setport(PORTA)) != 0 ) { 
printf( "ERROR: setport = %d\n", result); 
exit(O); 

} 

/♦ INITIALIZE THE FRONT END PROCESSOR ♦/ 

if( (result=initpl{DCE.&encode.eot, 96001, CCITT.ASCII_EVEN_OATA)) ) { 
printf( "ERROR; initpl = Xd\n", result); 
exit(O); 

} 


/♦ SET THE ACTIVE PORT TO "B" •/ 
if( {result=setport(PORTB)) != 0 ) { 


ppintf( "ERROR: setport = Xd\n", result); 
exit(O); 

} 


55 

50 

16 

02 

03 

01 

38 

31 

45 
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/• INITIALIZE THE FRONT END PROCESSOR •/ 

if( (resuU*initpl(DTE.&encode.eot, 96001. CCITT.ASCII_EVEN_DATA)) ) { 
printf( "ERROR: initpl = %d\n", result); 
ex1t(0); 

} 


/♦ 

♦ RECEIVE DATA 

•/ 

get_data(port) 
unsigned char port; 

{ 

extern unsigned int rxlen; /♦ global variable for receive data length •/ 
int i; 

unsigned char rxbuf[128]; 

setport(port) ; determine which port to use */ 
printf ("\nWaiting to receiveXn"); 

do { 

receive(rxbuf ) ; /♦ if rxlen=0 then no data was received •/ 

} while (rxlen==0); 

for(i»0;i<rxlen; i+H-) { 

1f( 1 X 15 ** 0 ) printf("\n") ; 

printf(*Xx ",rxbuf[i]); /♦ print results of data transfer ♦/ 

} 

.} 


/• 

♦ TRANSMIT DATA OUT 

•/ 

send_data( port , buf , 5uf_s i ze ) 
unsigned char port.^buf; 
int buf^size; 

{ 

setport(port) ; /• determine which port to use */ 

printf CVnRESULT OF TRANSMIT=Xd\n" .transmit{0x80,buf .buf_size)) ; 
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main( ) 

{ 

char ch; 

unsigned char atrans[100]; /• transmit array ♦/ 
int i ; 


/• INITIALIZE BOTH PORTS •/ 
init_ports( ); 
setport( PORTA); 


/• WAIT UNITL THE SYSTEM IS READY TO TRANSMIT •/ 

whne((tready())l*0) { /• loop while transmitter not ready ♦/ 


puts(CLEARS); /• clear screen •/ 
printf( "PRESS ANY KEY TO ABORT \n"); 
printf("TREAOY STATUS =Xd\n" . tready( )) ; 

if((ch = getch {_stdvt)) -1) /• check for key pressed ♦/ 

exit(O) ; 

} 

/• SEND OUT SOME DATA ♦/ 
for (1»0;i<»99;i++) 

atr8nsC1]-0x66; /• store hex 66 into the transmit array •/ 

printf ( "\nPress RETURN to send data from port *A* to port *B*\n"); 
getcharO; 

send_data( PORTA , at rans , i ) ; 

/• WAIT FOR SOME DATA ♦/ 
get_data( PORTS ) ; 

/• SEND OUT SOME DATA ♦/ 
for ( i=0; i<=99; i'»'+) 

atrans[i]*0x22; /• store hex 22 into the transmit array ♦/ 

printf ( "\nPress RETURN to send data from port 'B' to port 'A'\n"); 
getcharO; 

send_data( PORTB , atrans , i ) ; 
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/• WAIT FOR SOME DATA ♦/ 
get_data( PORTA) ; 

printf("\nPress RETURN to exit the programXn" ) ; 
getchar( ) ; 
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B.8 PRIMARY RATE INTERFACE LIBRARY 


Introduction The Primary Rate Library enables you to use the Chameleon 

32 Primary Rate Interface hardware with the C environment. It 
Is valid for both the ANSI and CEPT Primary Rate Interfaces. 
The library is called libpri.a and is in the /lib directory. 

In general, your application should include PRI library routines 
which enable you to set up and modify the Primary Rate 
Interface from within your application. However, when you 
start a C application from the Applications Selection menu, you 
must set up the PRI before you can access the Applications 
Selection menu to start the application. This can be 
accomplished in two ways: 

• You can access the PRI Setup menu before starting the 
C application. This is done by pressing F7 Phy&cl in the 
main configuration menu. 

• You can save the PRI Setup menu as part of the 
DEFAULT configuration file. The PRI Is then 
automatically set up when the Chameleon is booted or 
reset. 

When the C application Is then started, it uses the PRI Setup 
menu parameters. Your application can then use other 
routines to modify the setup or use PRI functions, as required 
by your test. If the application contains a PRI library setup 
routine, the application setup overrides the menu setup. 

When starting an application from the C Shell, if your 
application contains a valid PRI setup routine, it is not 
necessary to access the PRI Setup menu prior to starting your 
application. 

Chapter 3.1 describes he procedure for starting applications 
from the C Shell and from the Applications Selection menu 


Note You cannot use the C PRI library and the primary application 

at the same time. (The primary application enables the user 
to monitor and modify the PRI at run time.) The primary 
application is useful for Monitoring applications and non-C 
simulation applications, but results in an error message when 
used simultaneously with the C PRI library. The primary 
application is described in the Chameleon Protocol 
Interpretation Manual, Chapter 11. 
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The functions are described on the following pages: 

FUNCTION PAGE 

Pri ^version B.8-3 

SetPrimary B.8-4 

Also refer to Appendix B.1 for a description of common library 
functions and error codes. 

Several sample programs using the PRI library are provided at 
the end of this section. 
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Pri ^version 

Declaration char Tri ^version() 

Description This function returns a pointer to a string which indicates the 

date of the Primary Rate Interface library version. 
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SetPrimary 

Declaration 

Description 


int SetPiimary(cmclblock, resblock) 
int cmdblock [14]; 
int resblock [14]; 

This function has two parameters that are integer arrays. The 
size of the arrays must be at least 14. 

The cmdblock (command block) parameter contains the input 
values needed. The first item in cmdblock (index 0) is an 
integer specifying the requested function. The remaining 
entries in the command block are the arguments required for 
the function. Choices for selections which are not available in 
a given configuration are ignored (eg., Data Rate in CEPT). 
For details of the Primary Rate Interface, refer to the 
Chameleon 32 Monitoring Reference Manual, Chapter 11. 

The resblock (result block) parameter is an array containing 
the results. If any, of the operation requested In the cmdblock. 

The first entry In the result block (Index 0) Indicates whether or 
not the command In cmdblock was completed successfully. 
Zero indicates a successful completion. Other values that are 
returned are given in the next result block elements. 

When the requested operation cannot be done because of an 
existing selection, the currently selected values are returned. 

This is illustrated in the figure below: 


COMMAND 


RESULT 

Argument 1 


Result 1 

Argument 2 


Result 2 

etc. 


etc. 


Figure B.8-1: SetPrimary Function 
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Channel Number/ 
Time Slot 


The commands listed below are available as the first item in 
cmdblock. Note that the commands are different for Primaiy 
Rate Interface boards A and B. Currently only board A is 
available. 


Board A 

Board B 

Command 

1 

101 

Setup 

2 

102 

Resynchronize 

3 

103 

Reset 

4 

104 

Channel functions 

5 

105 

Signal functions 

6 

106 

Get status 

7 

107 

Change status 

8 

108 

Reserved 

9 

- 

Enable trace 


Each command is described on the following pages. 


When selecting a channel number (ANSI) or time slot (CEPT) 
for a command, the following convention applies: 

• Enter the channel number itself to select a channel or 
time slot for line 1 {T1 or R1). For example, for ANSI, 
the argument 24 would select channel number 24 on line 
1 . 

• Enter the channel number + 100 to select a channel or 
time slot for line 2 (T2 or R2) For example, for ANSI, the 
argument 124 would select channel number 24 on line 2. 
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Error Codes 

resbiock[0] The error codes for resblock[0] are the same for ail Primary 

Rate Interface Library commands, and are listed below. 

If a command is successful, the current configuration is 
returned as resblock[1] - resblock[11]. The result reflects the 
structure of the cmdblock[1] - cmdblock[11] of the Setup 
command. 

If a command fails because of an invalid parameter, the invalid 
parameter is returned in cmdblock[1]. If a command fails for 
something other than an invalid parameter, the current 
configuration is returned. 


CODE 

MEANING 

NOTES 

0 

Successful 

resblock[1] - resbiockfll] return the current 
configuration 

1 

Primary Rate Interface board 
not installed 


2 

Setup already done 

To change the setup, first use the Reset 
command to reinitialize, and tiien use the 

Setup command 

3 

Invalid channel number/time 
slot 

resblock[1] returns the invalid channel or 
time slot 

4 

Selection already in use 

resblockfl] - resblock[11] return the current 
configuration 

5 

Channel already assigned 

resblock[1| - resblock[11] return the current 
configuration 

10 

Command not implemented 



Figure B.8-2: resblockfO] Error Codes 
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Setup 

cmdblock[0] = 1 

cmdblock[0] = 101 This command is used to initialize all parameters. The Reset 

command (cmdblock[0] = 3/103) must be used before using 

Setup again. 

cmdblock[1] mode 1 Monitor 

2 Simulate 

cmdblock[21 framing 1 D4 

2 ESF 

3 SL96 

4 CEPT 

cmdblock[31 idle data 
8 bit value 

cmdbiock[4] idle signal 

2 or 4 bit value 

cmdblock[5] DSOx receive 

Channel/time slot 

cmdblock[6]' Codec receive 

Channel/time slot 

cmdblock[7]' DSOy receiver/transmitter 
Channei/time slot 

cmdblock[8]“ Codec transmitter 

Channel/time slot (This parameter is irrelevant 
for Monitor mode and is ignored.) 

cmdblock[9]" Milliwatt transmitter 

Channel/time slot (This parameter is irrelevant 
for Monitor mode and is ignored.) 

cmdblock[1 0]* status line 1 

One byte (See Figure B.8-3 on the next page) 

cmdblock[1 1] status line 2 

One byte (See Figure B.8-3 on the next page) 

* These functions are available on Line 1 only. 


NOTE: When the system is in Monitor Mode, no 

Transmit facilities are available 
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Bit 


7 6 5 4 3 2 1 0 

xxxxxxxx 



Zero si^^ression 

1 =On 
Reserved 
Slgn^l^ 

1 =On 

Data rate (ANSI only) 

0 = 64k 
1=56k 

Milliwatt tone (CEPT only)* 
0 = 820 

1 = 1020 

DSO Bit inversion 

0 = Off 

1 =On 

CRC Enable (CEPT only) 

0 = CRC Enable off 

1 = CRC Enable on 
Reserved 


* Available on Line 1 only 


Figure B.8-3: Status Byte Interpretation 


if you use the Setup command and the setup has already 
been done, you will receive the error resblock(0] = 2 (Setup 
already done). In this case, use the Reset command 
(cmdblock{0] - 3) to reinitialize, and then use the Setup 
command with the new configuration. 


Resynchronize 
cmdblock[0] = 2 

cmdblock[0] = 102 Argument None 

This command resets the Primary Rate Interface and 
reconfigures with the current setup. 


Reset 

cmdbiock[0] = 3 

cmdblock[0] = 103 Argument None 

This command resets the Primary Rate Interface and puts the 
lines in repeater mode. The interface can then be 
reconfigured using the Setup command. 
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Channel Functions 




cmdbiock[0] - 4 




cmdblock[0] -104 

cmdblock[1] mode 

0 

Retain current setup. 



1 

Override current setup. (See 




below) 


cmdblock[2] selection 

1 

DSOx receive 



2 

Codec receive 



3 

DSOy transmit 



4 

DSOy receive 



5 

Codec transmit 



6 

Milliwatt transmit 



7 

Reset transmit channel 



8 

Reset receive channel 



9 

Idle data 



10 

Idle signal 


cmdblock[3] channel number (if cmdblock[21 = 1 - 8 j 

1 - 24 D4/ESF line 1 

1-31 CEPT line 1 


cmdblock[3] Idle bits (if cmdblock[2] = 9 or 10) 

8, 4, 2 bits 


if there is an existing selection which conflicts with the new 
request, cmdblock[1] (mode) determines whether the 
command is executed. For example, if the request is for 
Codec transmitter on channel 2, but channel 2 is already being 
used by Milliwatt transmitter, the following occurs: 

• if mode 1 is selected, the old selection is reset. For this 
example, the Milliwatt transmitter is reset, and channel 2 
assigned to Codec transmitter. 

• If mode 0 is selected, the old selection is retained and the 
command request is not executed. For this example. 
Milliwatt transmitter is retained on channel 2 and the error 
code resblock[01 = 4 (Selection already in use) and the 
current configuration are returned. 

In general, if you wish to execute channel functions regardless 
of their previous selection or non-selection, use mode 1 
(cmdblock[1] = 1). 
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cmdblock[0] = 5 
cmcibiock[0] * 105 

Signal Functions cmdblock[1] selection 1 Resynchronize 

This selection resets and 
resynchronizes the line. 

2 Normal 

This selection puts the line back 
to normal mode of operation after 
selecting any other choice of this 
command. 

3 Repeater 

This selection loops the receive 
line back to the transmit line. 

4 Alarm 

This selection transmits the Yellow 
alarm signal in D4/ESF mode, or 
the Remote alarm in CEPT. 

5 Transparency (for line 1) 

This selection causes all channels 
from the received line to be 
looped back as channels in the 
transmit line. For channels with 
transmit functions (codec, 
Milliwatt, Data Y), the incoming 

traffic is replaced by the signal 

from the selected transmitter. 

cmdblock[2] line number 1 Line 1 

2 Line 2 
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Get Status 
cmdbiock[0] - 6 

cmdblock[0] = 106 Argument None 


This command returns the status of the line. 

resblock[1] 0 Synchronized 

1 Loss of signal 

2 Yellow Alarm 

4 Loss of framing 


Change Status 
cmdblocktO] = 7 
cmdbiock[0] = 107 

cmdblock[1] line 1 or2 

cmdblock[2] status xxxxxxxx (see below) 


This command changes the operating modes of different 
selections, for example, zero suppression and DSO bit 
inversion. The choices are coded in bits, as shown in Rgure 
B.8-4. 
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Bit 


7 6 5 4 3 2 1 0 


xxxxxxxx 



oi'Sf' 

1 =On 
Reserved 
Signaling 

1 =On 


Data rate (ANSI only) 

0 = 64k 
1=56k 

Milliwatt tone (CEPT only) 
0 = 820 

1 = 1020 

DSO Bit Inversion 

0 = Off 

1 =On 

CRC Enable (CEPT only) 

0 = CRC Enable off 

1 = CRC Enable on 
Reserved (must be 1) 


Figure B.8-4: Status Byte Interpretation 

Enable trace 

cmdbiock[0] * 9 This command is useful for debugging your programs. 

cmdblock[1] 8 trace bits (see below) 


Bit 


7 6 5 4 3 2 1 0 
xxxxxxxx 



Trace I/O to the hardware 

0 = Off 

1 =On 

Trace Command Block 

0 = Off 

1 =On 

Trace Result Block 
0 = Off 
1=On 

Trace Configuration 

0 = Off ' 

1 =On 
Reserved 
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Sample Programs 


There are four sample PRI 
Program Disk. They are: 


• 

pria.c 

Sets up 

• 

prib.c 

Sets up 

• 

cepta.c 

Sets up 

• 

ceptb.c 

Sets up 


programs on the C Sample 

an ANSI PRI on Port A. 
an ANSI PRI on Port B. 
a CEPT PRI on Port A. 
a CEPT PRI on Port B. 


PRIA.C This sample program demonstrates transmitting and receiving 

over a PRI on Port A using the libbop.a and the libpri.a 
libraries. 

#include <stdio.h> 

^Include <chafii.h> 

#include <video.h> 

#include <nitosux.h> 

/• initalize cmd array for set primary function - setup as follows: 


1 

mode 

* 

simulate 

2 

framing 

= 

04 

3 

idle data 

s 

hex 55 

4 

Idle signal 

3 

11 binary 

5 

DSOx rec 

3 

channel 15 

6 

codec rec 

3 

channel 1 

7 

OSOy xmit 

3 

channel 15 

8 

codec xmit 

3 

channel 1 

9 

millawatt 

3 

channel 4 

10 & 11 

status #1&2 

3 

hex 01 


zero suppression on 
signaling off 
data rate 64000 
nillawatt tone 820hz 
DSO bit inversion off 
CRC enable off 
line 2 off 

0 1 2 3 4 5 6 7 8 9 10 11 12 13 •/ 

int cmd []* {1, 2, 1, 0x65, 3, 15, 1, 15, 1. 4. 0x01, 0x01, 0, 0 }; 
int rsp []» {0, 0, 0, 0x00, 0, 00, 0, 00, 0, 0, 0x00, 0x00, 0, 0 }; 

exit_program( ) 

{ 

printf ("\n\nPress RETURN to end this program\n"); 

getcharO; 

exit(O); 

} 
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malnO 

{ 

extern unsigned int rxlen; global variable for receive data length */ 

int i, result; 

unsigned char atrans[303,rxbuf[128],c; /♦ transmit & revieve arrays •/ 

initialize the ISDN PRIMARY RATE (layer 1) interface •/ 

SetPrimary (cmd.rsp); 
if(rsp[0] !« 0) { 

printfCXnERROR: RESULT SETPRIMARY « %d\n". rsp[03); 
exit_program{); 

} 

pause(125*i44S); /♦ wait for the primary (layer 1) to initialize ♦/ 

/• initialize the front end processor for port A */ 

if ( (result«setport( PORTA)) l» 0 ) { 
printf ("ERROR: setport * Xd\n*, result); 
exit_program( ) ; 

} 

if( {resuU«1n1tpl(ISDN,NRZ, 640001, FILL7E)) l» 0 ) { 
pr1ntf( ‘ERROR: initpl • Xd\n", result); 
ex1t_progrM(); 

} 

Store data into the transmit array */ 
for(i»0;i<*25;i++) 

atrans[1] « 65 i; /• fill transmit buffer with upper case letters ♦/ 

/• transmit data & get result ♦/ 

printf ("Press Return to send data from port A\n"); 
getcharO; 

if( ( result®transmit(6000_CRC,atrans, i ) ) I* 0 ) { 
printf("\nERR0R: result~%d\n" .result) ; 
exit_program(); 

} 

/>» receive the data from the the other device or port 
printf("\nWaiting to receive data, (press 'q* to quit)\n"); 
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do { 

rece1ve( rxbuf ) ; /* if rxlen^O then no data was received */ 

if ({c=getch(_stdvt)) == *Q‘ I| c == 'q*) exit(O); 

} while (rxlen==0); 

for(i=0; i<rxlen;i++) 

printf{"Xc ", rxbuf [i]); /• print results of data transfer ♦/ 

exit_prograin( ); 

} 
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PRIB.C This sample program demonstrates transmitting and receiving 

over a PRI on Port B using the libbop.a and the libpri.a 
libraries. 


#include 

<stdio.h> 


#include 

<cham.h> 


#include 

<video.h> 


#include 

<mtosux.h> 



/• initalize cmd array 

for set primary function - setup as follows: 

1 

mode » 

simulate 

2 

framing * 

04 

3 

idle data - 

hex 55 

4 

idle signal » 

11 binary 

5 

DSOx rec » 

channel 15 

6 

codec rec - 

channel 1 

7 

OSOy xmit » 

channel 15 

8 

codec xmit * 

channel 1 

9 

millawatt » 

channel 4 

10 & 11 

status #1&2 * 
zero suppression on 
signaling off 
data rate 64000 

millawatt tone 820hz 

OSO bit inversion off 

CRC enable Off 

hex 01 


line 2 off 

0 1 2 3 4 6 6 7 8 9 10 11 12 13 •/ 

int cmd []» {101, 2. 1, 0x5S, 3. 15. 1. 15. 1. 4. 0x01. 0x01. 0. 0 }; 
int rsp []» {0, 0, 0, 0x00, 0, 00, 0, 00, 0, 0, 0x00, 0x00, 0, 0 }; 

exit_progpain( ) 

{ 

printf ("\n\nPpess RETURN to terminate this prograroXn"); 

getcharO; 

exit(O); 

} 
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main( ) 

{ 

extern unsigned int rxlen; /• global variable for receive data length •/ 
int i, result; 

unsigned char atrans[30], rxbuf[128],c; /• transmit & revieve arrays •/ 

/• initialize the ISON PRIMARY RATE (layer 1) interface •/ 

SetPrimary (crod^rsp); 
if(rspC0] 1= 0) { 

printf("\nERROR: RESULT SETPRIMARY = %d\n", rsp[0]); 
exit_program( ) ; 

} 

pause(125*H4S); /• wait for the primary (layer 1) to initialize •/ 

/• initialize the front end processor for port B ♦/ 

if ( (result=sotport(PORTB)) I* 0 ) { 
printf( "ERROR: setport = %d\n", result); 
exit_program( ); 

} 

1f( (result»initpl(ISDN,NRZ. 640001, FILL7E)) != 0 ) { 
pr1ntf( 'ERROR: initpl - MXn', result); 
ex1t_progra«(); 

} 

/• receive the data from the the other device or port 
printf("\nWaiting to receive data, (press ’q* to quit)\n"); 
do { 

receive( rxbuf ); /♦ if rxlen=0 then no data was received ♦/ 

if{(c=getch(_stdvt)) == *Q* || c == *q‘) exit(O); 

} while (rxlen*=0); 

for(i*0;i<rxlen;i-M-) 


printf("%c ",rxbuf[i]); /♦ print results of data transfer •/ 

/• Store data into the transmit array ♦/ 
for(i=0;i<=25;i++) 

atrans[i] = 97 + i; /♦ fill transmit buffer with lower case letters •/ 
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/♦ transmit data & get result •/ 

printf (**\n\nPress Return to send data from port RNn**); 
getchar(}; 

if( (result*transmit(6000_CRC,atrans,i)) != 0 ) 
printf("\n£RROR: result^XdXn" , result) ; 

exit_program(); 

> 
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CEPT.C This sample program demonstrates transmitting and receiving 

over a CEPT PRI using the libbop.a and the libpri.a libraries. 

^include <stdio.h> 

^Include <chain.h> 

#1nc1ude <v1deo.h> 

#inc1ude <mtosux.h> 

/* Initialize cmd array for set primary function - setup as follows: 
mode » simulate 

framing * CEPT 

idle data = hex 56 

idle signal * 11 binary 

DSOx rec - channel 15 

codec rec » channel 1 

OSOy xmit > channel 15 

codec xmit » channel 1 

millawatt - channel 4 

status #1&2 » hex 01 

zero suppression on 
signaling off 
data rate 64000 
millawatt tone 820hz 
DSO bit inversion off 
CRC enable off 
line 2 off 

0 1 2 3 4 5 6 7 8 9 10 11 12 13 

int cmd []= {1, 2, 3, 0x55, 3, 15, 1, 15, 1, 4, 0x01. 0x01, 0, 0 >; 
int rsp []= {0, 0, 0, 0x00, 0, 00, 0, 00, 0, 0, 0x00, 0x00, 0, 0 }; 

exit_program() 

{ 

printf ("\n\nPress RETURN to end this program\n"); 

getchar(); 

exit(O); 

} 


1 

2 

3 

4 

5 

6 

7 

8 

9 

10 & 11 
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ma1n( ) 

{ 

extern unsigned int rxlen; /• global variable for receive data length ♦/ 
int i, result; 

unsigned char atrans[30], rxbuf[128],c; /♦ transmit & revieve arrays ♦/ 

/• initialize the ISDN PRIMARY RATE (layer 1) interface •/ 

SetPrimary (cmd,rsp); 
if(rspC0] !» 0) { 

printfCXnERROR: RESULT SETPRIMARY = XdXn", rsp[03); 
exit_program(); 

} 

pause(125'*^S); /• wait for the cept to initialize ♦/ 

/• initialize the front end processor for port A ♦/ 

if ( ( result»setport( PORTA) ) !® 0 ) { 
printf( "ERROR: setport * XdXn", result); 
exit_program(); 

} 

if( (resuU>inUpl( ISON, NRZ, 640001, FILL7E)) !< 0 ) ( 
printf( -ERROR: initpl » Xd\n-, result); 
ex'it_prograiii(); 

} 

/• Store data into the transmit array ♦/ 
for(i»0;i<*25;i*H') 

atrans[i] « 65 + i; /• fill transmit buffer with upper case letters ♦/ 

/• transmit data & get result ♦/ 

printf("XnPress Return to send data from port AXn"); 
getchar(); 

if{ (result»transmit(600D_CRC,atrans,i)) 1* 0 ) { 
printf("XnERR0R: result=%dXn", result) ; 
exit_program(); 

} 
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/• receive the data from the the other device or port •/ 
printf ("\nWaiting to receive data, (press *q’ to quit)\n'*); 
do { 

receive(rxbuf ); /• if rx1en-0 then no data was received •/ 

if({c»getch(_stdvt)) =* *Q* He »= *q’) exit(O); 

} while (rxlen®«0); 

for( i=0; iCrxlen; i-M-) 

printf("Xc '*,rxbuf[i]) ; /• print results of data transfer •/ 
exit_program(); 

> 
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CEPTB.C This sample program demonstrates transmitting and receiving 

over a CEPT PRI on Port B using the libbop.a and the libpri.a 
libraries. 


#1nc1ude <stdio.h> 
^include <cham.h> 
#iiiclude <v1deo.h> 
#include <intosux.h> 


1 

2 

3 

4 

5 

6 

7 

8 

9 

10 & 11 


/• Initialize crod array for set primary function - setup as follows: 
mode - simulate 


framing 

s 

CEPT 


Idle data 

s 

hex 55 


idle signal 

s 

11 binary 

OSOx rec 

* 

channel 

15 

codec rec 

s 

channel 

1 

OSOy xmlt 

s 

channel 

15 

codec xmlt 

s 

channel 

1 

millawatt 

s 

channel 

4 

status #1&2 

s 

hex 01 



zero suppression on 
signaling off 
data rate 64000 
millawatt tone 820hz 
DSO bit Inversion off 
CRC enable off 
line 2 off 


0 1 2 3 4 5 6 7 8 9 10 11 12 13 •/ 

Int cmd []* {101, 2, 3. 0x65, 3, 15, 1, 15, 1, 4, 0x01, 0x01, 0, 0 }; 
Int rsp []- {0, 0, 0, 0x00, 0, 00, 0, 00, 0, 0, 0x00, 0x00, 0, 0 }; 

exit_program() 

{ 

printf ( "\n\nPress RETURN to terminate this programXn") ; 

getcharO; 

exit(O); 

} 
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inain( ) 

{ 

extern unsigned int rxlen; /* global variable for receive data length */ 
int i,result; 

unsigned char atrans[30],rxbuf[128],c; /• transmit & revieve arrays •/ 

/• initialize the ISON PRIMARY RATE (layer 1) interface •/ 

SetPrinary (cmd,rsp); 
if{rsp [03 1= 0) { 

printf("\nERROR: RESULT SETPRIMARY = Xd\n", rsp[0]); 
exit.prograin{); 

} 

pause(125’*’MS); /♦ wait for the cept to initialize •/ 

/• initialize the front end processor for port B •/ 

if ( (result*setport( PORTS)) !* 0 ) { 
printf ("ERROR: setport * %d\n", result); 
exit_program(); 

} 

if( (result«initpl(ISDN,NRZ, 640001, FILL7E)) !* 0 ) { 
printf ("ERROR: initpl * Xd\n", result); 
exit_progra«(); 

} 


receive the data from the the other device or port */ 
printf ("\nyaiting to receive data, (press 'q* to quit)\n"); 
do { 

receive(rxbuf ); /• if rxlen*0 then no data was received ♦/ 


if((c=getch(_stdvt)) *Q* 1| c ** *q*) exit(O); 

} while (rxlen**0); 

f or( i*0 ; iCrxlen ; i-M-) 

printf ("Xc "^rzbufCi]); /• print results of data transfer •/ 

/• Store data into the transmit array •/ 
for(i=0;i<=25;i++) 

atrans[i] * 97 + i; /• fill transmit buffer with lower case letters •/ 


Tekelec 


B.8-23 


Version 2.5 




Chameleon 32 C Manual 


Appendix B.8: Primary Rate Interface Library 


/• transmit data & get result ♦/ 

printf ("\n\nPress Return to send data from port B\n"); 
getcharO; 

if( (result*transmit(600D_CRC,atrans,i)) !* 0 ) 
printf ( "VnERROR: resul t=Xd\n" , resul t) ; 

exit_program(); 

} 
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B.9 ASYNC C LIBRARY 


Introduction The Async C Library (libasc.a) is valid for asynchronous 

simulation. It is in the \lib directory. 

The functions are described on the following pages: 


FUNCTION PAGE 


INITP1 B.9-2 

RECEIVE B.9-4 

TBREAK B.9-5 

TRANSMIT B.9-6 

TREADY B.9-7 


Also refer to Appendix B.1 for a descripition of the common 
library functions and error codes. 
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INITP1 

Description 

Declaration 

Range 


This function initializes the Front End Processor and loads its 
simulation software. 


int initp1{type, encode) 
int type; 

struct ASC CTRL "encode; 


type 0 DCE 
1 DTE 

encode This is a structure that defines the control 
characters for the Async protocol. It it defined as 
follows: 

struct ASC CTRL 

int bitrate; 
int parity; 
int stop; 
int data; 
int duplex; 
int block; 

unsigned char eob; 

}; 


bitrate 

1 

50 

7 

1200 


2 

75 

8 

2400 


3 

110 

9 

4800 


4 

150 

10 

9600 


5 

300 

11 

19200 


6 

600 



parity 

0 

None 




1 

Odd 




2 

Even 



stop 

0 

1 

Stop bit 



1 

1.5 

Stop bits 



2 

2 

Stop bits 


data 

5 

5 Data bits 



6 

6 Data bits 



7 

7 Data bits 



8 

8 Data bits 
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duplex 0 Full Duplex 
1 Half Duplex 


block 0 Block mode 

1 Character mode 


eob (End of block character) 
Range: 0 - OxFF 


Returns 


0 Successful 

-1 One or more parameter errors 

-2 Front End Processor program could not be loaded 

-3 Port is busy 

See also the global error codes on page 
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RECEIVE 


Declaration 


Description 


Returns 


Example 


int receive(frame) 
char frame; 


This function receives a block or a character from P1, and 
places the frame starting at the address pointed to by the 
passed variable frame. The external global variable rx/en is 
set to the length of the received frame. If rxlen - 0, then no 
data was received. 

The block parameter of the initpl function enables you to 
select either block or character mode. In block mode, a block 
of data is returned only when the end of block character is 
received. The end of block character is defined with the eob 
parameter in the initpl function. If the end of block character 
is not received, rxlen = zero. 


0 Good BCC or no frame waiting 

1 Bad BCC 

2 initpl not performed 

3 Overflow 

See also the global error codes on page B.1-1. 


• • • 
do { 

receive (frame) ; 

} while (rxlen == 0); 
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TBREAK 


Declaration 


Description 

Returns 


int tbreakO 


This function transmits a break sequence. 


See the global error codes on page 
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TRANSMIT 


Declaration 


Description 


Returns 


int transmit(frame, length) 
char “frame; 
int length; 


This function transmits the number of bytes specified by the 
passed variable length, starting at the address pointed to by 
the passed pointer "frame. 


0 Successful 

1 Front End Processor busy (transmitting previous frame) 

2 Initpl not performed 

3 Parameter error 

4 Buffer overflow 

See the global error codes on page B.1-1. 
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TREADY 

Declaration 


Description 


Returns 


int tready{) 


This function returns the status of the Front End Processor 
transmitter. 


0 Transmitter is ready for next frame 

1 Transmitter is busy (sending previous frame) 

2 initpt not performed 

3 Overflow 

See the global error codes on page 
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SAMPLE PROGRAMS There are three sample Async programs on the C 

Sample Program Disk. They are: 

• ascach.c 

• ascbch.c 

• ascasch.c 
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ASCACH.C This sample program demonstrates transmitting and receiving 

in character mode on Port A over a V.24 interface using the 
libasc.a library. 

ji^include <std1o.h> 

^include <chain.h> 

^include <video.h> 
struct ASC_CTRL; 

main() 

{ 

char ch; 

struct ASC_CTRL encode; 

extern unsigned int rxlen; /* global variable for receive data length */ 
unsigned char atrans[30], rxbuf[2]; /• transmit & receive arrays •/ 
int result, i; 

encode. bitrate = 89600; 

encode. parity = EVEN; 

encode. stop * STOPl; 

encode. data = 0ATABIT7; 

encode. duplex - HALF; 

encode, bloci^ * CHARMOOE; 


encode. eob • 0x40; only used in block mode */ 

rxbuf[l] = '\0*; /• initialize position 1 ♦/ , 

/• SET THE ACTIVE PORT TO "A" •/ 


if( (result»setport(PORTA)) != 0 ) { 
printf( "ERROR; setport * %d\n", result); 
exit(O); 

} 

/♦ INITIALIZE THE FRONT END PROCESSOR ♦/ 

if( (result=initpl(DCE,&encode)) ) { 
printf{ "ERROR: initpl = Xd\n", result); 
exit(O); 

} 
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/♦ WAIT UNITL THE SYSTEM IS READY TO TRANSMIT •/ 

while( tready{)!=0 ){ /♦ loop while transmitter not ready ♦/ 

puts(CLEARS); /• clear screen •/ 

printfCTREADY STATUS =%d\n“ . tready( ) ) ; 
printf ("PRESS *q’ TO ABORT \n"); 

if((ch * getch (_stdvt)) =- 'q') /♦ fail safe ♦/ 

exit(O) ; 

} 

/• SEND OUT SOME DATA •/ 
for (i*0;i<=25;i-*-+) . 

atrans[i]= 65 + i ; /• store upper case letters into the transmit array •/ 
atrans[i]=0x40; /• sentinel with an 0 character •/ 

printf ("\n hit RETURN to send the data out of port *A'\n"); 
getchar( ); 

for(i=0;i<=26;i++) { 

whi1e(tready( ) 1= 0 ){ /• wait for the previous frame to send ♦/ 

if((ch = getch {_stdvt)) == ’q’) /♦ fail safe ♦/ 

exit(O); 

} 

printf( "RESULT OF TRANSMIT Xd)=%d\n" , i .transmitCatrans-t-i , 1) ) ; 

} 

/• WAIT FOR SOME DATA FROM THE OTHER DEVICE •/ 

printf ( "\nWaiting to receiveVn"); 

do { 
do { 

receive(rxbuf ) ; /• if rxlen=0 then no data was received ♦/ 

if({ch = getch {_stdvt>) == *q') /• fall safe ♦/ 

exit(O); 

} while (rxlen*=0); 

printf ("%s ".rxbuf); /• print results of data transfer ♦/ 

} while (rxbuf[0] 1= /• transfer complete ? •/ 

printf ( "\nPress RETURN to exit the program\n"); 
getchar( ) ; 


} 
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ASCBCH.C This sample program demonstrates transmitting and receiving 

in character mode on Port B over a V.24 interface using the 
libasc.a library. 


^include <stdio.h> 

^include <cham.h> 

X^include <video.h> 
struct ASC^CTRL; 

ma1n( ) 

{ 

char ch; 

struct ASC_CTRL encode; 

extera unsigned int rxlen; /* global variable for receive data length */ 
unsigned char atrans[30], rxbuf[2]; /• transmit & receive arrays ♦/ 
int result, i; 


encode. bit rate = 
encode. parity * 
encode. stop > 
encode. data - 
encode. duplex - 
encode. block » 
encode. eob * 


B9600; 

EVEN; 

STOPl; 

DATABIT7; 

HALF; 

CHARMOOE; 

0x23; 


/♦ only used in block mode •/ 


rxbuf[l] * ’NO*; /• initialize position 1 ♦/ 


/• SET THE ACTIVE PORT TO "B" •/ 

if( (result*setport(PORTB)) !* 0 ) { 
printf( "ERROR: setport = %d\n", result); 
exit(O); 

} 


/• INITIALIZE THE FRONT END PROCESSOR •/ 

if( (result=initpl(DTE,&encode)) ) { 
printf( "ERROR; initpl = %d\n", result); 
exit(O); 

} 
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/♦ WAIT UNITL THE SYSTEM IS READY TO TRANSMIT ♦/ 

whne( tready()!=0 ){ /♦ loop while transmitter not ready •/ 

puts(CLEARS); /• clear the screen •/ 

printf( -PRESS *q‘ TO ABORT \n-); 
ppintf("TREAOY STATUS =Xd\n- , tready( ) ) ; 
if((ch - getch (_stdvt)) ** *q’) 
exit(O); 

} 

/• WAIT FOR SOME DATA FROM THE OTHER DEVICE ♦/ 

printf (-\nWaiting to receiveXn-); 

do { 
do { 

receive(rxbuf ); /• if rxlen=0 then no data was received ♦/ 

if((ch = getch {_stdvt)) == *q*) /• fail safe ♦/ 

exit(O); 

} while (rxlen**0); 

printf (-Xs -,rxbuf); /• print results of data transfer ♦/ 

} while {rxbuf[0] != *0*); /• transfer complete ? •/ 

/♦ SEND OUT SOME DATA •/ 
for (i»0;i<*25,-i*»--^) 

atrans[i]* 97 + i; /♦ store lower case letters into the transmit array ♦/ 
atrans[i]=0x23; /• sentinel with a # character •/ 

printf("\n hit RETURN to send the data out of port ‘B'Xn"); 
getchar( ) ; 


for(i=0;i<=26;i++) { 

while(tready( ) 1= 0 ){ /♦ wait for the previous frame to send ♦/ 

if((ch = getch (_stdvt)) == 'q') /• fail safe •/ 

exit(O); 

} 

printf (“RESULT OF TRANSMIT Xd)=Xd\n" , 1 .transiiiit(atrans+i , 1)) ; 


printf ( "\nPress RETURN to exit the programXn" ) ; 
getchar( ) ; 


} 
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ASCABCH.C 


^include <stdio.h> 
^include <cham.h> 
^include <v1deo.h> 
struct ASC_CTRL; 


This sample program demonstrates transmitting and receiving 
in character mode on a Dual Port machine over a V.24 
interface using the libasc.a library. 


1nit_ports( ) 

{ 

struct ASC_CTRL encode; 
int result; 


encode. bitrate 
encode. parity 
encode. stop 
encode. data 
encode. duplex 
encode. block 
encode. eob 


B9600; 

EVEN; 

STOPl; 

DATABIT7; 

HALF; 

CHARMOOE; 

0x40; 


/* only used in block mode **/ 


/• SET THE ACTIVE PORT TO "A" •/ 

if( (result=setport(PORTA)) != 0 ) { 
printf ("ERROR: setport = Xd\n", result); 
exit(O); 

} 


/• INITIALIZE THE FRONT END PROCESSOR •/ 

if( {result=initpl(OCE,&encode)) ) { 
printf{"ERROR: initpl = td\n", result); 
exit(O) ; 

} 


/• SET THE ACTIVE PORT TO "B" •/ 

if( ( resu1t=setport( PORTS ) ) !* 0 ) { 
printf( "ERROR: setport = Xd\n", result): 
exit(O); 

} 
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/• INITIALIZE THE FRONT END PROCESSOR •/ 

if( (result=in1tpl{DTE,&encode)) ) { 
printf{ "ERROR: initpl = %d\n*, result); 
exit(O); 

} 

} 

send_data(port,buf ,buf_size) 
unsigned char port, *buf: 
int buf_size; 

{ 

int i, result; 
unsigned char ch; 

setport(port) ; /♦ the port sending the data ♦/ 

for( 1*0;i<=buf_size; i++) { 

wh11e(tready( ) !« 0 ){ /♦ wait for the previous frame to send •/ 

if{(ch = getch (,stdvt)) == ’q’) /• fail safe ♦/ 

exit(O); 

} 

if( (result=transmit{buf+i,l)) != 0 ) 

printf( "ERROR: RESULT OF TRANSMIT Xd)=%d\n" . i . result) ; 

} 

} 

get_data(port) 
unsigned char port; 

{ 

extern unsigned int rxlen; /♦ global variable for receive data length ♦/ 
unsigned char ch, rxbuf[ 23 ; /♦ receive array ♦/ 

rxbuf[l] * *\0*; /* Initialize position 1 ♦/ 

printf ("\nWaiting to recelveXn"); 

setport(port) ; /• the port receiving the data ♦/ 

do { 
do { 

receive( rxbuf ) ; /♦ if rxlen=0 then no data was received •/ 

1f((ch = getch (_stdvt)) =* *q') /♦ fail safe •/ 

ex1t(0); 

} while (rxlen=sO); 

pr1ntf("%s ", rxbuf); /♦ print results of data transfer ♦/ 

} while ( rxbuf [0] !=*©'); /♦ transfer complete ? ♦/ 

} 
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inain( ) 

{ 

char ch; 

unsigned char atrans[30]; /♦ transmit array ♦/ 
int i ; 

/• INITIALIZE BOTH PORTS •/ 
init_ports( ) ; 

/• WAIT UNITL THE PORT A IS READY TO TRANSMIT ♦/ 
setport{ PORTA ) ; 

whi1e( tready()!=0 ){ /• loop while transmitter not ready ♦/ 

puts(CLEARS) ; /♦ clear screen •/ 

printf("TREADY STATUS =%d\n" ,tready( )) ; 
printf("PRESS 'q* TO ABORT \n"); 

if((ch = getch (_stdvt)) == 'q*) /♦ fail safe ♦/ 

ex1t(0); 

} 

/♦ SEND OUT SOME DATA OUT PORT A •/ 
for (i*0;i<*25;i*»*+) 

atrans[i]= 65 + i; /• store upper case letters into the transmit array •/ 
atrans[1]»0x40; /* sentinel with an 3 character */ 

printfCXn hit RETURN to send the data out of port ’A'Xn"); 
getchar( ); 


send_data( PORTA, atrans, i ) ; 

/• WAIT FOR SOME DATA FROM PORT A •/ 
get_data(PORTB); 

/♦ SEND OUT SOME DATA OUT PORT B •/ 
for *( i=0; i<*25; i++) 

atrans[i]= 97 + i; /♦ store lower case letters into the transmit array •/ 
atrans[i ]*0x40; /• sentinel with an 0 character */ 


printf("\n hit RETURN to send the data out of port 'B’\n"); 
getchar( ); 

send_data( PORTB , atrans , i ) ; 
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/♦ WAIT FOR SOME DATA FROM PORT B •/ 
get_data( PORTA); 


printf ("\nPress RETURN to exit the programVn" ) ; 
getchar( ); 
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B.10 ANALYSIS LIBRARY 


Introduction The C Analysis Library enables you to design custom analysis 

programs using the C language on the Chameleon 32. The 
name of the library is libanal.a and is located in the /lib 
directory. 

The functions are described on the following pages: 


FUNCTION 

PAGE 

INIT_ANAL 

B.1 0-2 

GETEVENT 

B.1 0-5 

RESET ANAL 

B.1 0-7 


Also refer to Appendix B.1 for a description of the common 
library functions and error codes. 


A sample program is provided following the functions. 
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INIT_ANAL 

Declaration 


Description 


Range 


Note 


Appendix B. 10: Analysis Library 


#include <cham.h> 

int init anal(port, protocol, par) 

int porfTprotocol; 

union PARBLOCK *par; 


This function initializes the hardware and loads the analysis 
software. Events are returned only for the port(s) selected by 
port. 


Port 0 Port A 

1 Port B 

2 Port A and B 


Protocol 

1 

BOP 


2 

ISDN 


7 

ASYNC 


8 

BSC 

Par: 




union PARBLOCK and the parameters are defined in 
a:\include\cham.h 


union PARBLOCK { r BOP parameter block 7 

struct { 

unsigned short encode; 

} pbop; 

struct ■( r Bisync parameter block 7 

unsigned short table; 
unsigned short bcc; 
char synd; 
char sync2; 
unsigned short parity; 

}pbisync; 

struct { r Async parameter block 7 

unsigned short baud; 
unsigned short parity; 
unsigned short databit; 

}pasync; 
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BOP/ISDN 


ASYNC 


BSC 


If Protocol = 1 (BOP) OR 2 (ISDN), the following 
parameter must be initialized: 

par- > pbop.encode 0 NRZ 

1 NRZI 


If Protocol = 7 (Async), the following three parameters 
must be initialized: 


par- > pasync.baud 


2 75 baud rate 

3 110 

5 300 

6 600 

7 1200 

8 2400 

9 4800 

10 9600 

11 19200 


par- > pasync.parity 0 None 

1 Odd 

2 Even 


par- > pasync.databit 5 


5 data bit 

6 6 data bits 

7 7 data bits 

8 8 data bits 


If Protocoled (BSC), the following parameters must be 
initialized: 


par- > pbsync.table 0 ASCII 

1 EBCDIC 

par- > pbsync.bcc 0 CRC16 

1 LRC 

2 CCITT 


par->pbsync.sync1 Range: 0 - Oxff 
par- > pbsync.sync2 Range: 0 - Oxff 


AND if par- > pbsync.table is initialized to ASCII the 
following parameter must also be initialized: 


par- > pbsync.parity 0 None 

1 Odd 

2 Even 
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Returns 


0 Successful 
-1 Parameter error 

-2 Port B not available (Not a Dual Port machine) 
-3 Cannot load analysis files 

-4 Simulation is running 

-5 Port is busy 

See also the global error codes on page B.1-1. 
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GETEVENT 


Declaration 


Description 


Note 


#include <cham.h> 

int getevent(pevent) 
event *pevent; 

This function gets an event from the line, if available. The 
structure below will be filled with the event information upon 
returning from the function call. 

typedef struct { 

unsigned short type; 
unsigned short length; 
unsigned short buflen; 
unsigned char ‘pdata; 
long seconds; 
long ms20; 

unsigned short special; 
unsigned short crc; 
unsigned short flags; 

} event; 

The getevent function copies event.buflen bytes of the frame 
data to the user data buffer (event.pdata). event- > pdata and 
event- > buflen must be initialized before calling the routine. If 
the length of the frame data received is greater than the data 
buffer length, the data will be truncated. 


event.type A bit-mapped information element 

described in the figure below. 
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Returns 


event.length 

event.pdata 

eventampm 

event.seconds 


The length of the data 

Data buffer address that points to the 
frame ( must be initialized by user) 

The time stamp flag for morning or evening 

The number of seconds elapsed since 
12:00 midnight or noon 


event.ms20 The number of 20 microsecond units 
elapsed since the second, which wraps 
around at 50,000 


event.buflen 


eventcrc 


Data buffer length ( must be initialized by 
user) 

Contains the crc value of the frame 


event.flags For BOP only, contains the number of 

flags. 

event.special Contains different information based on 
bits 10 - 12, as follows; 

If a baud rate event, the baud rate change 
event will contain the new baud rate value. 


If a lead transition event, the bits are 
interpreted as follows: 


Bits 

7 

6 

5 

4 

3 

2 

1 

0 

DCE 

CTS 

DSR 

DCO 

Rt 

SDCO 













DTE 

RTS 

DTR 








Otherwise the value in special should be 
ignored. 


0 Successful 
-1 No new events 

-2 Data overwitten (buffer wrapped) 

-3 Wrong port selected 

See also the global error codes on page B.1-1. 
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RESET 


Declaration 


Range 


Description 


Returns 


ANAL 


int reset anal{pon) 

int port; 


port 


0 Port A 

1 Port B 

2 Ports A and B 


This function resets the acquisition processor (Front End 
Processor board). 


See the global error codes on page B.1-1. 
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Sample Program The program below (bscanal) configures the Chameleon 32 to 

analyze BSC traffic over the Basic Rate Interface, When an 
event is received, the main program calls the dispframe 
function, which interprets and displays the event. It displays 
the following information: 

• Port (A or B) is displayed in white 

• DCE (red) or DTE (green) event 

• Event type in hex 

• Timestamp 

• Length, if data frame > 0 

• Data in hex, if any 

#1nclude <ciiaa.h> 

#1nc1u<le <v1deo.h> 

finclude <stdio.h> 

extern long _stdvt; 
extern char getch( } ; 

char ch; 
let Ten; 

#define SP SetBas1c(c,rsp); 

#define setup() SP 

#def1ne chan_func() c[03M;c[l]=0;c[2]*3;c[3]=l; SP 

#def1ne jresetO c[0]s3; SP • 

■a1n() 

{ 

event ^pevent* eventst; 
char bttffer[256]; 

Int val : 

int c [5]. rsp [5]; 

union PARBLOCK «par; 

resetO; 
setupO; 
reset_anal(); 
chan_f unc( ) ; 

pr1ntf(*setting SET-UP 

d1sab1ecur(_stdvt); /♦ disables cursor •/ 
pevent - fteventst; /* allocates event space 
val »1n1t_ana1 ( PORTA, ISON «&par) ; 

If ( val I* 0 ) { /• check return status ♦/ 

printf("in1t_anal failed, error code =Xd\n*,val); 
ex1t(0);} 

puts(*Hit <q> to abort, hit space bar to halt\n*); 

pevent->pdata » (unsigned char^)boffer; /• initialize buffer address •/ 

pevent- >buflen = 250; /• initialize buffer length ♦/ 
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while {(ch = getch(_stdvt) ) !=*q* ){ /♦ If q is pressed, aborted •/ 

if ( ch== • •) 
getchar( ); 

if ( getevent (peveiit)== 0) { 

dispfra«e (pevent); 

} 

} 

reset_ana1 ( PORTA ) ; 
enablecur (_stdvt); 

} 

dispfraae (pe) 
event ^pe; 

{ 

if ( (pe->type & EM^SIDE) == EM^SIDE ) 

puts(”\033[32a\nOCE Event*); /* displays OCE events in red */ 

else 

puts (*\033[31a\n0TE Event*); /• displays DTE events in green •/ 

printf(*Type = X04x Sec XSld Usec(20) X51d\n*, pe->type, pe->seconds, pe->as20); 

if (pe-> length) { /• determines if event was a data frame •/ 

printf ("length = Xd\n*, pe'>length); 

len»(( unsigned int)pe'>length > (unsigned int)pe'>buflen) ? pe->buflen : pe~>length; 
hex_du«p(len, pe-‘>pdata); 

} 

printf(*\033[0fl\n*); /• restores the screen color •/ 

} 

hex_duap(len, data) /* displays data in ASCII "/ 

int len; 

unsigned char ^data; 

{ 

unsigned int a,b; 
for (a=0 ,b=0; a!=len; a*«H») { 
if (b == 0) 

printf (•\nX4x\t* , a); 
printf(*X02x *,data[a]); 
if (++b == 16) 
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B.11 MULTI-LINK LAPD LIBRARY 


The Multi-Link LAPD library is an optional C library which must 
be purchased in addition to the Chameleon 32 C Development 
System. 

The Multi-Link LAPD library supports a total of 64 logical links. 
The library is named libmiapd.a and is located in the a:\iib 
directory of the hard disk. 

Note Some functions in the Multi-Link LAPD library provide a degree 

of compatibility with the single-link LAPD library. These 
functions enable you to quickly upgrade your existing code to 
take advantage of the Multi-Link LAPD features without having 
to rewrite your program. However, these functions should not 
be used in new programs, and should be eventually taken out 
of upgraded program, as they may be removed in some future 
library version. 

TGI Byte Multi-Link LAPD includes the option of using the TGI (Terminal 

Group Identifier) address byte. (If used, the TGI is the third 
byte of the LAPD Address field.) The set tgi{) function 
assigns a TGI value to the currently selected liriR in the range 
0-14. The simulator handles the TGI byte as follows: 

• If a valid TGI value is assigned to a link, the TGI byte is 
used. 

• If a TGI value > 14 is assigned to a link, the TGI byte is 
not used. 

• If an invalid TGI value (0 or 14, depending on LAPD 
implementation) is assigned to a link, it enables you to 
test the recovery of the Device Under Test to an invalid 
TGI value. 


Link Selection The Multi-Link LAPD library includes functions which enable 

you to control the use of 64 logical links. Each of the 64 links 
is referred to by a unique link number In the range 0 - 63. 
Each of the 64 logical links has its own SAPI and TEI value, 
which are assigned as follows: 

1. Select one of the 64 links (0 - 63) using set link. All 

links default to state 9, disabled. 

2. Assign the link a SAPI value using set sapl. 

3. Assign the link a TEI value using set tei. 
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Frame Status 
Word 


General Notes 


Note 


4. If applicable, assign the link a TGI value using the 

set tgi function. 

5. When you select a link using set link, you can then use 
the other functions to set the linlT on (slon), set the link 
off (slof), and transmit and receive messages. 


A two-byte frame status (frstat) which is attached at the 
beginning of each received message provides access to the 
following information: 

• Frame type 

• Number of link which received the frame 

• Command or response frame 

• Poll/Final bit value 

The get rxstat function returns the low order byte of frstat. 

The get rlink function returns the high order byte of frstat. 


If two or more links have the same address (SAPI/TEI or 
SAPI/TEl/TGI combination), received frames will be considered 
to belong to the highest link number matching that address. 

A link is disabled by selecting the link and setting the SAP I of 
TEI to an invalid value. You should ensure that the link is in 
the disconnected state before you disable it. If a link is 
disabled while in a connected (multi-frame) state, the device 
under test will see it as a Layer 1 failure. 

Using an invalid TGI value disables the use of the TGI byte. It 
does not disable the link. 

Setting the SAPI and/or TEI value to an invalid value sets the 
link to the disabled state (9). This provides an easy means of 
testing lost link recovery and providing a means of ignoring 
unused links. 

There are two functions which get the state of a link. The 
status function gets the state of the selected link. The 
link stat function gets the state of any specified link. 

get freelink returns the number of the lowest numbered 
disabled link, search link returns the number of the lowest 
link matching a speciTied SAPI/TEI combination, find link 
returns the number of the lowest link matching a specified 
SAPI/TEl/TGI combination. 


Tekelec 


B.11-2 


Version 2.5 





Chameleon 32 C Manual 


App. B.1 1 : Multi-Link LAPD Library 


Functions 


The following functions are in the Multi-Link LAPD library. Also 
refer to the common functions and error codes described in 
Appendix B.1. Programming tips and examples are provided 
beginning on page B.1 1-52. 


find ^link . . . 

get_freeiink() 
get_fwaiting . 

get link() . . . 

get Inksapi 

get Inktei 

get Inktgi 

get meswaiting 

get ^rlinkO . . 

get rntei . . . 

get_rsapi . . . 
get_rxstat() 
get_sapi() . . 
get_sconfig () 
get__sim () . . 
get_tei() . . . 
get_tgi() . . . 

get ^window . 

initpl 

Iink_stat . . . 

receive 

s_n200 .... 

s n201 .... 

S_t200 

S_t203 

set__sconfig . 
set_link .... 
set_net () 

set rntei . . . 

set_rsapi . . . 
set_sapi . . . 

set sub 0 . . 

set_tei .... 
set_tgi .... 
set window . 

setfig 

slof 0 

slon {) 

srch Ink . . . 

start sim . . . 

statusO 

trans 

transmit .... 

trui 

trxcni 

trxidc 

trxidr 

trxmi 


B.1 1-4 
B.1 1-5 
B.1 1-6 
B.1 1-7 
B.1 1-8 
B.1 1-9 
B.11-10 
B.1 1-11 
B.il-12 
B.1 1-13 
B.11-14 
B.11-15 
B.11-16 
B.11-17 
B.11-18 
B.11-19 
B.1 1-20 
B.1 1-21 
B.1 1-22 
B.1 1-23 
B.1 1-24 
B.1 1-25 
B.1 1-26 
B.1 1-27 
B.1 1-28 
B.1 1-29 
B.1 1-30 
B.1 1-31 
B.1 1-32 
B.1 1-33 
B.1 1-34 
B.1 1-35 
B.1 1-36 
B.1 1-37 
B.1 1-38 
B.1 1-39 
B.11-40 
B.1 1-41 
B.1 1-42 
B.11-43 
B.11-44 
B.11-45 
B.11-46 
B.11-47 
B.1 1-48 
B.1 1-49 
B.1 1-50 
B.1 1-51 
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flnd_link() 

Declaration 


Description 


Returns 


int find link(sapi,tei>tgi) 
int sapiHei, tgi; 

sapi SAPI value of the link, in the range 0 - 255 (SAPI > 63 is 
invalid, resulting in don’t care value) 

tei TEI value of the link, in the range 0 - 255 (TEI > 127 is 
invalid, resulting in don!t care value) 

tgi TGI value of the link, in the range 0 - 255 0 - 255 (TGI 
> 15 is invalid, resulting in don’t care value) 


This function returns the number of the lowest link matching 
the SAPI/TEI/TGI values specified. An invalid SAPI, TEI, or 
TGI value is treated as a don’t care value for that parameter, 
so that setting a parameter to an invalid value returns the first 
link matching the valid parameters. 


0-63 Matching link number 

-1 No match found 
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get ^freelinkO 

Declaration int get freelink() 


Description This function gets the link number (0 

link. 


Returns 


0-63 Disabled link number 

-1 No free links available 

-2 initpl not performed 


63) of the first disabled 
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get_fwaiting 

Declaration 


Range 

Description 


Returns 


int get fwaiting (Inkn) 
char liiRh; 


Inkn 0-63 


This function gets the number of l-frames waiting to be 
transmitted on link Inkn. 


0-7 Number of l-frames waiting to be sent by link Inkn 


See also the global error codes on page B.1-1. 
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get link{) 

Declaration 


Description 


Returns 


int get link() 


This function gets the number of the link which is currently 
under user control. 


0-63 Current link number 

-1 initpl not performed 
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get Inksapi 

Declaration 


Range 

Description 

Returns 


int get Inksapi (Inkn) 
char IfiRh; 


Inkn 0-63 


This function gets the SAPI value for link Inkn. 

0-63 SAP! value assigned to link Inkn 

> 63 SAPI value disabling link Inkn 

See also the global error codes on page B.1-1. 
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get Inktei 

Declaration 

Range 

Description 

Returns 


int get Inktei (Inkn) 
char IhRh; 


Inkn 0 - 63 


This function gets the TEl value for link Inkn. 


0-127 TEl value assigned to link Inkn 

>127 TEl value disabling link Inkn 


See also the global error codes on page B.1-1. 
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get Inktgi 

Declaration 

Range 

Description 

Returns 


int get Inktgi (Inkn) 
char Iritcn; 


Inkn 0 - 63 


This function gets the TGI value for link Inkn. 


0-14 TGI value assigned to link Inkn 
15 - 255 TGI value disabling use of TGI on Inkn (the link is 
not disabled) 


See also the global error codes on page B.1-1. 
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get meswaiting 


Declaration int get meswaiting () 


Description This function gets the number of messages waiting to be 

received from the Front End Processor (FEP). 

Note This function returns the number of messages buffered by the 

FEP. The library buffers one additional message. 


Returns 0-32 Number of messages waiting to be received from 

the FEP 

See also the global error codes on page B.1-1. 
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get rlink() 

Declaration 


Description 


Returns 


int get rlink() 


This function gets the number of the link which sent the last 
received message. This is the high order byte of the frame 
status word frstat passed by the FEP. 


0-63 Current link number 

-1 No messages received yet 

-2 initpl not performed 
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get rntei 

Declaration 


Range 

Description 


Returns 


int get rntei (val) 
int valT" 


Range of val is untested 


This is a dummy function to maintain compatibility with existing 
single link LAPD programs that are being upgraded to Multi- 
Link LAPD; Refer to the LAPD library in Appendix B.3 for 
more Information. 


This function always returns zero. 
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get rsapi 

Declaration 


Range 

Description 


Returns 


App. B. 1 1 : Multi-Link LAPD Library 


int get rsapi (val) 

int val; 


Range of val is untested 


This is a dummy function to maintain compatibility with the 
existing single link LAPD programs that are being upgraded to 
Multi-Link LAPD. Refer to the LAPD library in Appendix B.3 for 
more information. 


This function always returns zero. 
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get rxstatO 


Declaration char get rxstatO 


Description This function gets the low order byte of the frame status word 

frstat, which contains the frame type, C/R bit and P/F bit of 
the last received message. 


Returns 


0 - 0xC3 frstat value (interpreted as shown below) 

OxFF No messages received yet 

OxFE initpl not performed 


7 

6 

5 

4 

3 

2 

1 

0 


High bit/low bit 


00 

01 

10 

11 


Ul frame 
XID frame 
l-frame 
FRMR 


Reserved 


0 = Command frame 

1 = Response frame 


0 = Poll/ Final bit clear 

1 = Poll/ Final bit set 


Examples 


0x41 Non-final XID response 

0x02 l-frame command 

0xC3 Final FRMR response 
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get_sapi() 

Declaration 


Description 


Returns 


int get sapi{) 

This function gets the SAPI value of the link currently under 
user control. 

0 - 255 SAPI for current link 

Also see global error codes on page B.1-1. 
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get sconfig () 

Declaration int get_sconfig () 


Description This function returns a copy of the current control configuration 

byte, which can be interpreted as shown in the figure below. 


76543210 


Bit 


Reserved 


Interframe Fill 

0 ~ Set interframe fill to value 7E 

1 = Set interframe fill to value FF 


Reserved 


Status Changing Frames 

0 = Poll normaliSet poll bit normal on status changing 

frames SABM(E) and DISC). 

1 = Poll set (Set poll bit on status changing frames 

SABM(E) and DISC.) 


SABM(E) Response 

0 = UA only. Stop generating SABM(E) collisions. 

1 = UAanaSABM(l). Generate SABM(E) collisions. 


XID Poll Bit 

00 = No XID frames polled. 

01 = Poll only XID frames without l-fields. 

10 = Poll only XID frames with l-fields. 

1 1 = Poll all XID frames 


XID Exchange 

0 = Stop transmitting XID's on T203 timeout. 

1 = Transmit XID command on T203 timeout. 
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get Sim () 

Declaration 


Description 


Returns 


int get sim () 


This function returns a copy of of the network/subscriber 
selection. 


0 Network 

1 Subscriber 
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get_tei() 

Declaration 


Description 


Returns 


int get tei() 


This function gets the TEI of the link currently under user 
control. 

0 - 255 TEI for current link number 

Also see global error codes on page 
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get_tgi() 

Declaration 


Description 


Returns 


int get tgi() 


This function returns the TGI value of the link currently under 
user control. 


0-14 TGI for current link number 

15 - 255 TGI value disabling use of TGI on the link (the link 
is not disabled) 

Also see global error codes on page B.1-1. 
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get ^window 

Declaration 


Range 

Description 


Returns 


int get window (Inkn) 
char IhRh; 


Inkn 0-63 


This function gets the number of outstanding l-frames on link 
number Inkn. 


0-7 Number of unacknowledged l-frames of link Inkn 
See also the global error codes on page B.1-1. 
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App. B.11: Multi-Link LAPD Library 


inltpl 

Declaration 


Description 


Note 


Ranges 


Returns 


int initpl (interface, sta, encode, bitrt) 
int interface, sta, encode; 
long bitrt; 


initpl loads the Front End Processor (FEP) code for the libraiy 
and starts simulation. Predefined values exist in miklib.h to aid 
in setting up the call to this function, sta is the station type 
and selects the initial sense of the command/response bit. The 
library permits reselection of the station type at any time, 
encode selects the physical data encoding bitrt sets the 
data rate when simulating a DCE device. 


This function is identical to and interchangeable with the 
start sim function. It has been included in the Multi>Unk 
LAPD" library for downward compatibility with the single link 
LAPD library. 


interface 

0 

V-type interface (DCE) 


1 

V-type interface (DTE) 


2 

ISDN interface 

sta 

0 

NETWORK 


1 

SUBSCRIBER 

encode 

0 

NRZ 


1 

NRZl 

bitrt 

Any long integer value from 


See the global error codes on page B.1-1. 
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link stat 

Declaration int link stat(n) 

char n; 


Range 

Description 

Returns 


n 0-63 

This function gets the current state of link n. 

0-9 Current state of link (see table below) 

See also the global error codes on page B.1-1. 


STATE 

LINK STATUS 

0 

Link Disconnected 

1 

Link Connection Requested 

2 

Frame Rejected 

3 

Disconnect Requested 

4 

Information Transfer 

5 

Local Station Busy 

6 

Remote Station Busy 

7 

Local and Remote Station Busy 

8 

Remote Station not Responding 

9 

Link Disabled 
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App. B. 1 1 : Multi-Link LAPD Library 


receive 


Declaration 


Description 


int receive(dest addr) 
char 'dest addfT 


This function receives a message from the FEP by performing 
the following tasks: 

• It polls the FEP to see if any received messages are 
available 

• It transfers the message contents to the user defined 

buffer pointed to by dest addr 

• The total length of the message (including the frame 
status bytes frstat) is placed in the global variable rxien 

The frstat word is accessible by calling get riink and 

get__rxstat so that you can interpret and respond to a 
message quickly. The frstat bytes are attached to the 
beginning of each received message so that several 
messages may be received, sorted, interpreted, and 
individual responses made. 

It is up to the user to ensure that the destination buffer is long 
enough to contain the message. Generally, a length equal to 
N201 + 2 is adequate. 
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App. B.11: Multi-Link LAPD Library 


s n200 


Declaration 


Range 

Description 

Returns 


int s n200 (val) 
int vaT; 


val 1 - 255 


This function sets the maximunn number of retries (N200). 


0 Successful 

See also global error codes on page B.1-1. 
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App. B.1 1 : Multi-Link LAPD Library 


s n201 


Dectaration 


Range 

Description 

Returns 


int s n201 (val) 
int val; 


val 1 - 512 


This function sets the maximum length for an l-frame (N201 ). 


0 Successful 

See also global error codes on page 
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App. B.1 1 : Multi-Link LAPD Library 


s t200 


Declaration 


Range 


Description 


Returns 


int s t200 (val) 
int val; 


val 0 - 255 


This function sets the time allowed for the remote station to 
respond (T200). Setting this value to 0 disables the T200 
timer. 


0 Successful 

See also global error codes on page 
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s t203 


Declaration 


Range 


Description 


Returns 


int s t203 (val) 
int vaT; 


val 0 - 255 


This function sets the maximum time between frames (T203). 
On time out, a polled RR or XI D command is transmitted, 
depending on the configuration selection. Setting this value to 
0 disables the T203 timer. 


0 Successful 

See also global error codes on page B.1-1. 
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App. B. 11 : Multi-Link LAPD Library 


set link 


Declaration 


Range 

Description 


Returns 


int set link(n) 

char n; 


n 0-63 


This function puts link n under user control. Only one link at a 
time can be under user control. 


0 Successful 

-1 Parameter out of range 

-2 initpl not performed 

-3 Timeout 
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App. B.1 1 ; Multi-Link LAPD Library 


set net () 

Declaration 


Description 


int set net () 


This function sets the simulation side to network. The 
Chameleon can simulate either a network or subscriber 
device. 

When the Chameleon 32 emulates a network. It sends 
commands with the C/R bit set to one, and responds with the 
C/R bit set to zero. It sends the selected SAPI and TEI with 
the C/R bit automatically set in accordance with CCITT Q. 921 . 
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App. B.11: Multi-Link LAPD Library 


set rntel 


Declaration 


Range 

Description 


Returns 


int set_rntei (val, tei) 
int val, tei; 


Range of val and tei is untested 


This is a dummy function to maintain compatibility with existing 
LAPD single-link programs that are being upgraded to Multi- 
Link LAPD. Refer to the LAPD library in Appendix B.3 for 
more information. 


This function always returns zero. 
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set rsapi 

Declaration 


Range 

Description 


Returns 


int set_rsapi (val, sapi) 
int val, sapi; 


Range of val and sapi is untested 


This is a dummy function to maintain compatibility with existing 
LAPD programs that are being upgraded to Multi-Link LAPD. 
Refer to the LAPD library in Appendix B.3 for more 
information. 


This function always returns zero. 
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set sapi 

Declaration 


Range 


Description 


Returns 


int set_sapi(v) 
char v; 


Accepted range of v is 0 - 255. A value over 63 disables the 
selected link. 


This function sets the SAPI value for the link under user 
control. The SAPI (Service Access Point Identifier) indicates 
the layer two service type requested or supported. Normal 
values are: 

0 Call Control procedures 

1 6 Packet communication procedures 

63 Management procedures 

64 - 255 Disable link 


0 Successful 

-1 Parameter out of range 

-2 initpl not performed 

-3 Timeout 
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App. B.11: Multi-Link LAPD Library 


set sconfig 


Declaration 


int set_sconfig (byte) 
int byte; 


Description 


This function sets the value of the control configuration byte, 
interpreted as shown in the figure below. 


76543210 


Bit 


Reserved 


Interframe Fill 

0 Set interframe fill to value 7E 

1 = Set interframe fill to value FF 


Reserved 


Status Changing Frames 

0 = Poll normal (Set poll bit normal on status changing 

frames SABM(E) and DISC.) 

1 = Poll set (Set poll bit on status changing frames 

SABM(E) and DISC.) 


SABM(E) Response 

0 = UA only. Stop generating SABM(E) collisions. 

1 = UA anci SABM(E). Generate SABM(E) collisions. 


XID Poll Bit 

00 = No XID frames polled. 

01 = Poll only XID frames without l-fields. 

10 = Poll only XID frames with l-fields. 

1 1 = Poll all XID frames 


XID Exchange 

0 = Stop transmitting XID's on T203 timeout. 

1 = Transmit XID command on T203 timeout. 


Returns 0 Successful 

See also global error codes on page 
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set sub 0 

Declaration 


Description 


int set sub () 


This function sets the simulation side to subscriber. The 
Chameleon can simulate either a network or subscriber 
device. 

When the Chameleon 32 emulates a LAPD subscriber, it 
sends commands with the C/R bit set to zero, and responds 
with the C/R bit set to one. It sends the selected SAPI and 
TEI with the C/R bit automatically set in accordance with 
CCITT Q. 921. 
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set tei 


Declaration 


Range 


Description 


Returns 


int set tei(value) 
char value; 


value The TEI value to use for the link, as follows: 

0-127 Valid TEI values 

128 - 255 Invalid TEI value, which causes the link 
to be disabled 


This function sets the TEI value for the link under user control. 
The TEI (Terminal Endpoint Identifier) Is a value assigned to 
and may be associated with a single terminal and a given 
point-to-point data link connection. At any time, a given 
terminal endpoint (TE) may contain one or more TEIs. 

This value may be assigned by the carrier at the time of 
equipment installation, or may be automatically assigned on a 
cail-by-caH basis. The broadcast value is associated with all 
user-side data link entities with the same SAPI, regardless of 
other assigned value(s). 


Normal values are: 


0-63 
64 - 126 

127 

128 - 255 


Non-Automatically assigned values 
Automatically assigned values 
Broadcast value 
Disable link 


0 Successful 

-1 Parameter out of range 

-2 initpl not performed 

-3 Timeout 
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App. B. 1 1 ; Multi-Link LAPD Library 


set ^tgi 

Declaration 


Range 


Description 


Returns 


int set tgi{value) 
char value; 


value The TGI value to use for the link, as follows: 
0-14 Valid TGI values 
15 - 255 Disables the use of the TGI byte 


This function sets the TGI (Terminal Group Identifier) value for 
the link under user control. If used, the TGI is the third byte of 
the LAPD Address field. 

If an invalid TGI value (0 or 14, depending on LAPD 
implementation) is assigned to a link, it enables you to test the 
recovery of the Device Under Test to an invalid TGI value. 


0 Successful 

-1 Parameter out of range 

-2 initpl not performed 

-3 Timeout 
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set ^window 

Declaration 

Range 

Description 

Note 

Returns 


int set_window (val) 
int val; 


val 1-7 


This function sets the maximum number of outstanding frames 
on each link. 

The total of outstanding frames + the number of frames 
passed to the FEP waiting to be transmitted + the number of 
messages over 16 bytes long waiting to be received from the 
FEP may not exceed 80. 


0 Successful 

See also global error codes on page B.1-1. 
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setflg 

Declaration 


Range 


Description 

Returns 


int setflg (flag) 
int flag; 


flag 1 0x7E fill 

0 OxFF fill 


This function selects an Interframe fill pattern. 


0 Successful 

See also global error codes on page B.1-1. 
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slot 0 

Declaration 


Description 


Returns 


int slot 0 


This function sends a DISC and waits for a UA frame. This is 
equivalent to the CCITT primitive dl release. 


0 Successful 

Also see global error codes on page B.1-1. 
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slon 0 

Declaration 


Description 


Returns 


int slon () 


This function sends a SABME and waits for a UA frame. This 
is equivalent to the CCITT primitive DL establish. 


0 Successful 

Also see global error codes on page B.1-1. 
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srch ink 


Declaration 


Description 


Note 


Returns 


int srch lnk(sapi,tei) 
int sapirTel; 


This function returns the number of lowest link matching the 
specified SAPI/TEI. If you set one parameter to an invalid 
value, it returns the first link matching the valid parameter. In 
other words, any invalid value is a don’t care. 

To search for a link by specifying SAPI, TEI, and TGI, refer to 
the find link function. 


0-63 Number of lowest link matching parameters 

-1 No match found 
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Start Sim 


Declaration 


Description 


Note 


Ranges 


Returns 


int start sim (interface, sta, encode, bitrt) 
int interface, sta, encode; 
long bitrt; 


start sim loads the Front End Processor (FEP) code for the 

library and starts simulation. Predefined values exist in 
mlklib.h to aid in setting up the call to this function, sta is the 
station type and selects the initial sense of the 
command/response bit. The library permits reselection of the 
station type at any time, encode selects the physical data 
encoding, bitrt sets the data rate when simulating a DCE 
device. 

This function is identical to and interchangeable with the initpl 
function, initpl is included for downward compatibility with the 
single link LAPD library. 


interface 

0 

V-type interface (DCE) 


1 

V-type interface (DTE) 


2 

ISDN interface 

sta 

0 

NETWORK 


1 

SUBSCRIBER 

encode 

0 

NRZ 


1 

NR2I 

bitrt 

Any long integer value from 


See the global error codes on page B.1-1. 
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statusO 

Declaration int status() 

Description This function gets the current state of link under user control. 

Returns 0-9 Current state of link {see table below) 

See also the global error codes on page B. 1-1. 


STATE 

LINK STATUS 

0 

Link Disconnected 

1 

Link Connection Requested 

2 

Frame Rejected 

3 

Disconnect Requested 

4 

Information Transfer 

5 

Local Station Busy 

6 

Remote Station Busy 

7 

Local and Remote Station Busy 

8 

Remote Station not Responding 

9 

Link Disabled 
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trans 

Declaration 


Description 


Returns 


App. B; 1 1 : Multi-Link LAPD Library 


int trans (frame, address, len) 
int frame, len; 
char ‘address; 


This function transmits a frame, as follows: 
frame selects type of frame to transmit: 


0x80 

l-frame 

Sequenced (numbered) l-frame 

0x81 

Ul 

Unnumbered l-frame (NSI) 

0x82 

XIDC 

XID command frame 

0x83 

XIDR 

XID response frame 


address is a pointer to the first byte of the message to be 
transmitted. 

len is the actual length of the message to be transmitted. 
There are two restrictions on the message length: 

• l-frames should not exceed the value set in N201 
(maximum length of an l-frame) 

• The total length of the frame cannot exceed 512 bytes. 

0 Successful 

Also see global error codes on page B.1-1. 
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App. B.1 1 : Multi-Link LAPD Library 


transmit 


Declaration 


Description 


Note 


Returns 


int transmit (xioc, xlen) 
char *xloc; 
int xlen; 


This function transmits a message in a sequenced (numbered) 
l-frame. 

xioc is a pointer to the first byte of the mesisage to be 
transmitted. 

xlen is the actual length of the message to be transmitted. 
There are two restrictions on the message length: 

• l-frames should not exceed the value set in N201 
(maximum length of an l-frame) 

• The total length of the frame cannot exceed 512 bytes. 

The transmit function is provided for user convenience. If 
.extremely high data rates are required, the trans function 
should be used, as it is somewhat faster. 


0 Successful 

Also see global error codes on page B.1-1. 
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App. B.11: Multi-Link LAPD Library 


trui 


Declaration 


Description 


Note 


Returns 


int trui (xioc, xlen) 
char *xloc; 
int xlen; 


This function transmits a message in an unnumbered l-frame 
(Ul frame). 

xioc is a pointer to the first byte of the message to be 
transmitted. 

xlen is the actual length of the message to be transmitted. 
The total length of the frame must not exceed 512 bytes. 


The trui function is provided for user convenience. If extremely 
high data rates are required, the trans function should be 
used, as it is somewhat faster. 


0 Successful 

Also see global error codes on page B.1-1. 
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trxcni 


Declaration 


Description 


Returns 


int trxcni () 


This function transmits an XID command frame with no data 
field. 


0 Successful 

See also global error codes on page 
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trxidc 


Declaration 


Description 


Note 


Returns 


App. B. 1 1 ;■ Multi-Link LAPD Library 


int trxidc (xioc, xlen) 
char *xloc; 
int xlen; 


This function transmits a message in an XID command frame. 

xioc is a pointer to the first byte of the message to be 
transmitted. 

xlen is the actual length of the message to be transmitted. 
The total length of the frame must not exceed 512 bytes. 


The trxidc function is provided for user convenience. If 
extremely high data rates are required, the trans function 
should be used, as it is somewhat faster. 


0 Successful 

Also see global error codes on page B.1-1. 
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App. B.11: Multi-Link LAPD Li braty 


trxidr 


Declaration 


Description 


Note 


Returns 


int trxidr {xioc, xlen) 
char •xIoc; 
int xlen; 


Transmit a message in an XID response frame. 

xioc is a pointer to the first byte of the message to be 
transmitted. 

xlen is the actual length of the message to be transmitted. 
The total length of the frame must not exceed 512 bytes. 


The trxidc function is provided for user convenience. If 
extremely high data rates are required, the trans function 
should be used, as it is somewhat faster. 


0 Successful 

Also see global error codes on page B.1-1. 
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App. B.1 1: Multi-Link LAPD Library 


trxrni 


Declaration 


Description 

Returns 


int trxrni () 


This function transmits an XI D response frame with no data 
field. 

0 Successful 

See also global error codes on page B.1-1. 
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App. B.11: Multi-Link LAPD Library 


PROGRAMMING NOTES AND EXAMPLES 


This section provides general information about using the 
Multi-Link LAPD library. Following these general notes is a 
section on converting current LAPD C programs to Multi-Link 
LAPD programs. 


General Notes In your program, specify the Chameleon port being used by a 

call to the set port function. This is not necessary when 
using a Single Fort Chameleon, but it should be done to make 
your application portable. 

A call to initpt must be made to start the Front End Processor 
(FEP). This loads the FEP operating code and starts the 
simulation. The Chameleon is then ready to begin testing. 

Before frames can be transmitted or received, at least one link 
must be enabled. This is done by: 

a. Selecting a link (default is 0) using the set__llnk function 

b. Setting the SAPI and TEI to valid values. This is done by 
calling set sapi and set tei. 


Interpreting 

Received 

Messages To interpret a received message, you must know the SAPI 

value and the frame type of the received message. This 
information is available to you from the frame status bytes, and 
can be accessed using the technique shown below: 


receive(polfitr); 

if(rxleiis=0) 

return(O); 

f rtype*(get_rxsta( )&3) ; 
lnk=get_rlink(); 
sapval ~get_1 nksap( Ink); 


/*ex1t If no aessage received^/ 

/^get the frame type status bits^/ 

/^get nuaber of the link sending aessage*/ 
/^get the SAPI for that llnk^/ 


In this example, the frame type may be interpreted from frtype 
as follows: 


0 = Ul frame 

1 = XID frame 

2 = l-frame 

3 = FRMR 

sapval is the SAPI value assigned to the link on which the 
message was received. 
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Optimizing 
Transmit Speed 


Transmitting 

Responses 


To optimize speed for applications such as load generators, 

follows these guidelines: 

• The trans function is faster than the other transmit 
functions such as transmit, trui, trxidr, and trxidc. 

• If you are not concerned with the contents of the 
received messages, use the following technique to keep 
the receive buffer empty. This is faster than a call to the 
receive function in the transmit loop. 

if (get_aes«tg( )>=6) 
nush(); 

• Minimize input, output, and screen print operations in all 
tasks. Since the processor that runs the C shell also 
manages many of the I/O tasks, this will result in your 
simulation program running faster. 

• Run your program in background mode. This is done by 
adding an ampersand (&) at the end of the file name 
when starting the test from the C shell. For example: 

test& 

will run the program test in background mode. This 
causes the program to run at a higher priority and frees 
the C shell for other uses. This technique also reduces 
the number of windows available for other tasks, since a 
separate window is opened for each program running in 
background mode. 


In a test environment, the actual information content of a given 
message type is often fixed. In such cases, only the message 
type must be known in order to select the proper response. 
To simplify responding to message, predefine the content of 
responses in a message array. 

In the following program fragment, the following is assumed: 

• A set of responses and pointers to the responses has 
been defined earlier 

• SAPI/TEI combinations have been set up 

The program fragment uses a defined value TYPEOS, which is 
the offset to the byte in the message containing the message 

type. The call to fix cref extracts the call reference value 

from the received message and copies it into the selected 
response message. 
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respon(l( ) 

{ 

Char aestyp.^resp; 
int resp_len; 

rxlen^O; /* prepare to loop until aessage received */ 
«hi1e(lrxlen) 

receive(&rxaes[0] ) ; 

if((get_rxstat()&3)=2) /♦only respond to Ifraaes*/ 

{ 

■estyp=rxaes[TYPEOS]: /♦get aessage type froa rcvd aessage^/ 
saitch(aestyp) 

{ 

case CALL_SU: /•if asg is call setups/ 

/♦respond setup ack^/ 

resp=&su_ack; 

resp J en=SU_ACK_LEII ; 

break; 

a 


case RELEASE: /♦ if asg is release^/ 

/♦respond release coaplete^/ 
resp«&re1_capl t; 
respj en*REL_CIIPLT_LEII ; 

} 

fix_cref(resp); /♦set response call ref value^/ 
set_link(get_rlink()); /♦select link to send response^/ 
transait(resp,resp.len); /♦ send response^/ 

} 

fix_cref(dest) 

char ♦dest; 

{ 

int ref_val; 

ref val =rxaes[CREF_OS] ; 

♦(dest*»CREF_0S-2)=refval; /♦-2 to alloa for frstat bytes^/ 

} 
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Simulating an 
ASP 


The following program fragment demonstrates how to use the 
Multi-Link LAPD library to simulate an Assignment Source 
Point (ASP). The fragment selects a random TEI value and 
returns it to be assigned to the Device Under Test. 

This assignment function consists of two nested loops. The 
inner loop requests a random number until it gets one greater 
than 63 (64 to 126 are available for auto-assignment). It then 
exits to the outer loop where a search is made to see if the 
value Is in use. This assumes that each assigned TEI is set in 
an active link on the Chameleon. 


ass1gn_tei() 

{ 

char tei_val; 

vh11e(l) /• start outer loop •/ 

{ 

«iii1e(l) /♦ start inner loop ♦/ 

{ 

tei_val~rnd( 126) : 

if(te1_val>63) /• exit if good value ♦/ 
break; 

} 

if(srcli_lnk(64,tei_val)<0) invalid sapi=don*t care */ 
break; exit if no eatch, tei is ok to use */ 

} 

petupn(tei_val ) ; 

} 
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UPGRADING PROGRAMS TO MULTI-LINK LAPD 

Upgrading existing LAPD programs to Multi-Link LAPD has 
been made as simple as possible. Many such programs can 
be run with little or no modification. This section contains hints 
and suggestions to aid in modifying existing user programs 
that have problems with the Multi-Link LAPD library, and 
upgrading to take advantage of the new library features. 


Troubleshooting This section lists typical problems and solutions when 

converting LAPD C program to Multi-Link LAPD. It is assumed 
that the program will run when relinked with the LAPD library. 


Problem 


Problem 


You cannot establish a link because a SABME is not 
transmitted by the Chameleon on a slon() call. 

Solution 1; The selected link is probably disabled. Multi-Link 
LAPD defaults all SAPI/TEI combinations to an 
invalid value, thus disabling the link. With the 
LAPD library, the SAPI and TEI are assigned 
default values of 0. To enable a link, add 
set sapi and set ^tei calls using valid values. 

Solution 2: If you are using a V-type interface, and simulating 
a DTE, the Chameleon may not be receiving a 
clock from the Device Under Test. To determine 
this, set the interframe fill (setflg) to 0x7E. If the 
clock Is being received, the Chamelelon front 
panel red and green Data LEDs should both 
illuminate. 

You cannot establish a link because the Chameleon does not 
respond when a SABME is received. 

Solution 1: The SAPI/TEI combination Is not assigned to a 
link. This occurs in programs that set receive 
SAPI (RSAPl) and receive TEI (RTEI) values 
without setting the transmit SAPI and TEI to the 

same value. A call to set link(get ^freelnk()) will 

select an unused link. Tfien use set sapi and 
set tei to assign the SAPI/TEI comBihation to 
thaOnk. This must be done for each SAPI/TEI 
combination that might be received. 


Solution 2: The subscriber/network selection is incorrect. 

Your program may change this selection as 
desired, but remember that it is a global selection 
which affects all 64 links. 
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Problem 


Problem 


Problem 


The Chameleon rejects frames on some SAPI/TEI 
combinations because of an incorrect N(r) value. 

Solution 1: More than one link is assigned the same 
SAPI/TEI, and the libra^ is transmitting on one 
while the FEP is receiving on another. This can 

be avoided by adding a call to srch Ink before 

assigning SAPI and TEI values to determine 
whether the combination already exists. 

Solution 2: There is a modulus mismatch. The Multi-Link 
LAPD FEP codes run only Mod 128. 


Timeout problems. Timeout {T200,T203) problems will nearly 
always be caused by changing the SAPI/TEI combination on a 
link after it is established and in multi-frame mode. 

Solution 1: The preferred solution is to assign all SAPI/TEI 
combinations to different links. Subsequent 
SAPI/TEI changes can then be replaced with 
set link calls. 

Solution 2: A second option is to disable the T200 and T203 
timers in the Chameleon and the Device Under 
Test, and then re-establish the link at intervals to 
purge unacknowledged l-frames. 

This solution is not good practice and should be 
used temporarily while debugging a program. 


The Chameleon sends response messages on the wrong link. 

Cause 1: The correct link was not selected prior to 
transmitting the response. 

Cause 2: The link was selected based on the single-link 
LAPD frstat interpretation. 

Cause 3: The link selection was based on the wrong 
received message. 

There are two possible solutions. If your program 
receives and responds to messages one at a 
time, either solution will work. If a number of 
messages are received, then interpreted as time 
permits, use the second solution. 
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Solution 1: 


Solution 2: 


When a message is received (and a response is 

needed), call set Hnk(get rlink()). This selects 

the link from wFich the last message was 
received. 

Set the link to the value of the first byte of frstat in 
the received message. This selects the proper 
link regardless of the number of messages 
received after the one being interpreted. 
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SAMPLE PROGRAM 1: ASSIGNMENT SOURCE POINT (ASP) SIMULATOR 

This sample program causes the Chameleon to simulate an 
Assignment Source Point (ASP) which generates random TEI 
values and assigns them on demand. The program has three 
major parts: 

• Part one starts the Multi-Link LAPD simulator and 
initializes the Front End Processor (FEP). 

• Part two is the actual ASP simulator. 

• Part three is an exit routine that scans the state of all 64 
links, sends a disconnect to any that are in a multiple 
frame state, removes any assigned TEI’s, and then stops 
simulation. 


The ASP 

Simulator Fully simulating an ASP is more complex than it first appears. 

A number of tasks must be performed which, in this program, 
involve nested loops and subroutines. The outermost loop 
tests for user input, specifically the letter Q, and exits when it 
is typed and the current cycle is finished. Until this happens, 
it prepares the next inner loop by setting a one second 
resolution countdown timer to 30 seconds. 

The second loop contains a third loop which waits for the timer 
to count down to zero. While it is waiting for the timer, it is 
also waiting to receive a message from the FEP. If a 
message is received, a message interpreter routine is called 
to decide what to do with it. 

When the timer reaches zero, another loop is entered that 
scans links 1 - 63 for valid TEI values. For each valid TEI, an 
ID check message is sent. If an ID check response is 
received, a second wait loop is entered to see if another 
response is received. If two responses are received, the Rl 
and Al values are compared. If the Als match and the RIs do 
not, two users have the same TEI, so that TEI is removed. 


The Message 

Interpreter There are three calls to this subroutine, which returns values 

indicating the received message type. The actions taken 
depend on the message type, as follows: 

• If the message is not from link zero, it is not from a Ul 
frame, or it has a MEI other than 15, it is ignored. 

• If it is an id request, the assign() function is called. 
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Removing a TEI 


The Assignment 
Subroutine 


• If it is an id check response, the following occurs: 

^ If the call is from the thirty second time loop, an id 
check response message is ignored. This is based 
on the asumption that it was either sent in error, or 
was sent so late that, by the time the loop has 
started, the timeout routine has already removed 
the TEI. 

► At call 2, the Rl value is extracted from the 
message and saved, then a second timed receive 
loop Is entered. If another id check response is 
received at call 3, the Rl value is compared with the 
one from call 2, and if it is different, the TEI is in 
use by two subscribers and it is removed. 


To remove or unassign a TEI, the following occurs: 

• An ID remove message is sent. 

• The local link to which the TEI was assigned is disabled 
by giving it an invalid TEI. 


To assign a TEI, the following sequence occurs: 

• A call is made to get freelnk() to see if there is a link 

available for assignment. If a link is not available, the 
request is denied. 

• The Al value is examined. If the Al is 127, a counter is 
started in the range 64 to 1 26. 

• A search is made to see if this value has been assigned 
to any link, and if so, another number is generated. 

• Once an unassigned TEI value is found, it is assigned to 

the link obtained by the get freelnk() call and then sent 

in an ID assigned message. 

• If the Al value is less than 127, a request for a specific 
TEI, a check is made to see if it was already assigned. If 
so, it is denied, otherwise it is assigned. 
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#include <stdio.h> 
^include <chafli.h> 
^include <ctype.h> 
^include <f cnti . h> 
^include <init.h> 
#include <video.h> 


#def ine T201 20 

extern int rxlen; /•this is where receive puts the message length*/ 
char rmes[260],tmes[5]; /•Messages are stored in character arrays 

because it is easier to interpret the message and 
make a response.*/ 

main( ) 

{ 

int reti»lnkno; 

reti=startup( ) ; /•call the startup routine below*/ 
if(reti) /•if any problems, quit*/ 
exit(O); 

/•while all the links are still disabled, set up the layer 2 parameters*/ 

reti=s_t200(0); 

reti=s_t203(0); 

/•timers t200,t203 disabled to reduce irrelevant traffic*/ 

reti=s_n200(3); 
reti*s_n20l(260); 
reti*set_window(3) ; 

/•Initialize the xroit message array. This will be used for id check and remove*/ 
tmes[0]=15; 
tmes[l]*0; 
tmes[2]=0; 

/* Set up 1 link for broadcast management procedures*/ 

reti=set_link(0); 

reti=set_sapi(63); 

reti=set_tei(127); 

/• go do the ASP simulation until the user wants to quit */ 
aspsim( ) ; 

/• go stop things as gracefully as possible */ 
shut_down( ) ; 

} ' 


startup( ) 

{ 

int rets; 
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/♦attempts to start the FEP on port A and returns the results. Setup is 
DCE simulation, network, NR2 encoding, 16000 BPS. •/ 

rets*setport( PORTA); /•run this program on port a*/ 
return(initpl(0,0,0, 16000L)) ; 

} 

asps1m( ) 

{ 

int rets, rival 1, rival2; 

char lnkno,answer, tei ,ail,ai2,stop_f lag; 

rets*inittime( ) ; /•initialize the timers*/ 
stop_flag=l; 

while (stop_flag) /•loop until ’Q’ typed*/ 

{ 

settimer(2.T201) ; 
while(timer(2)&&stop_flag) 

{ 

if (toupper(getch(_stdvt))==*Q' )/*stop loop if *Q* typed*/ 
stop_flag=0; 
rets=receive{&rmes[0]) ; 
if ( rxlen) 

{ 

rets=interp( ) ; 

} 

} 

/'scan links for assigned TEIs and see if they are still in use*/ 
f or( 1 nltno=l ; 1 nkno<64 ; 1 nkno++) 

{ 

tei=get_lnktei(lnkno) ; 

if(tei>63 && tei<127)/*if link has a valid TEI */ 

{ 

/•build and send an id check message*/ 

tmes[3]=4;/*id check message type*/ 

tmes[4]=(tei<<l)+l; 

settimer(0,500); 

rets*l; 

while(rets&&timer(0)) 

rets=trui(&tmes[0] ,6) ;/*send check message*/ 

/•wait 2 seconds for an id response*/ 
answer^O; 

settiraer(2,2) ; /♦2 seconds is long enough*/ 
while(timer(2)) 

{ 

rets=receive(&rmes[0]) ; /*see if any messages*/ 
rets=0; 

if(rxlen) 

{ 

rets=interp();/* if so, see what to do*/ 

} 
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if(rets) /♦if id check response^/ 

{ 

rival l=rmes[4]+256^rmes[3]; 
ail=r(nes[6]; /• get ai byte*/ 
answer^l; /•flag TEI in use*/ 


} 

if(rets==l) /♦if id check response*/ 
break; /*then exit first timer loop*/ 

} 

/♦resend check message if no response received*/ 
if ( tanswer) 

{ 

settimer(0,500) ; 
rets=l; 

while( rets&&timer(0) ) 
rets=trui(&tmes[0],5) ; 

} 

/* start second %iait loop*/ 

settimer(2,2); /*2 seconds is long enough*/ 
whi1e(timer(2)) 

{ 

rets*receive(&rmes[0]) ; /*see if any messages*/ 
if ( rxlen) 

rets=interp( ) ;/* if so, see what to do*/ 
if(rets==l) /*if id check response*/ 

C 

answer^-*-;/* add 1 to answer*/ 
rival2*nDes[4]+256*rmes[3];/*get RI value*/ 
ai2-rmes[6]; /* get ai byte*/ 

} 

if(rets==l) /*if id check response*/ 
break; /*then exit first timer loop*/ 

} 

switch(answer) 

{ 

case 0:/*no response, TEI no longer in use*/ 
rmvtei(get_lnktei(lnkno) ) ; 
break; 

case 1:/*1 response, TEI in use*/ 
break; 

case 2;/*2 responses*/ 

/♦if different ri values and same ai, two entities have same TEI */ 

if ( ( rival 1! =rival2)&&(ai l==ai2) ) 
rmvtei(get_lnktei(lnkno) ) ; 


rmvtei(tei ) 
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char tei ; 

{ 

int rets; 

tnies[3]=6;/^id remove message type*/ 

/*ri = tei shifted left 1 bit and the Isb set*/ 
tines[4]=(tei<<l)'»-l; 
set_l ink(srch_lnk{266, tei ) ) ; 
if{getjink()>0) 

{ 

set_tei(266) ; 
set_sapi(265); 

set_link(0);/*back to management link*/ 
xyplot(0,0); 

printf(** removing tei %d \n",tei); 

settimer(0,500); 

rets=l; 

while( rets&&timer(0) ) 

rets*trui(&tmes[03,5);/*send id remove message*/ 

} 

} 

interp( ) 

{ 

int rets; 

/*return 0 if message not from link 0, not a UI frame, or not ASP entity id code*/ 
if (get_rlink( ) | 1 (get_rxstat( )&3)1 | rmes[2]!=16) 

* return(O); 

switch(rmes[5]) 

{ 

case 1: /*id request*/ 
rets*assign(); 
break; 

case 5: /*id check response*/ 
rets=l; 
break; 

default: rets=0; 

} 

return(pets) ; 

} 


xyplot (x, y) 

{ 

printf ("\033Clld;Xdf", y. x); 
fflush (stdout); 

} 


assign( } 

{ 

int rets; 

char Riestyp.ai.lnkno; 
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ai=( nnes[6]&0xfe)>>l;/*get requested TEI value*/ 
lnkno=get_f reelink( ) ;/*get a link to assign to the requestor*/ 

if(lnkno<0) /♦if no links available*/ 

{ 

retmes(3,ai ) ;/*deny TEI assignment*/ 
return(O); /* and leave*/ 

} 

if{ai<127) /*if specific TEI value requested*/ 

{ 

if(srch lnk(255 ,ai )<0)/*if requested TEI not in use*/ 

{' 

give_tei( lnkno,ai ) ;/*go make assignment*/ 
return(O) ; 

} 

/*if requested TEI is already in use*/ 
retmes(3,ai ) ;/*deny TEI assignment*/ 
return(O);/* and leave*/ 

} 

/*at this point, the request is for any TEI , and since there is a 
link free, there are at least 2 TEI values not in use. All we have to 
do is find one. While random number generation is more in complience 
with CCITT recomendations, the following code is simpler and yields 
more repeatable results.*/ 

for(ai=64;ai<127;ai++)/*loop until an unassigned TEI value reached*/ 

{ 

. rets=src-h_lnk(255,ai ) ;/*see if TEI in use*/ 
if(rets<0)/*if not, break out of loop*/ 
break; 

} 

give_tei(lnkno,ai);/*go make assignment*/ 
return(O) ; 

} 

give_tei(lnkno,tei ) 
char lnkno,tei; 

{ 

int rets; 

/♦setup the local link first*/ 
rets=set_l ink(lnkno) ; 
rets*set_sapi(0) ; 
rets=set_tei(tei ) ; 

/♦next, assign the TEI to the device under test and exit*/ 
xyplot(0,0); 

printf( "assigning tei Xd \n",tei); 
rets=set_l ink(O) ; 
retmes(2, tei ) ; 

/* return{);*/ 

} 

retmes(mestyp,ai ) 
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char mestyp,ai; 

{ 

int rets; 

/• send return message generated by inserting new message type and 
ai values into the last received message. This saves transferring the 
ri value into a new message.*/ 

rmes[5]*mestyp; 

rmes[6]*{ai<<l)+l; 

settimer(0,500); 

rets=l; 

wh i 1 e( rets&&timer( 0 ) ) 
rets=trui(&rmesC2],6) ; 

} 

shut_down( ) 

{ 

int rets; 
char Inkno; 

f or( 1 nkno> 1 ; 1 nkno<64 ; 1 nkno-J-^ ) 

{ 

rets=set_l ink(lnkno) ; 
if (status( )>0&&status( )<9) 
slofO; 

if {get_tei( )<127) 

rmvtei(get_tei( ) ) ; 


} 


} 
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SAMPLE PROGRAM 2: ASSIGNMENT SOURCE POINT (ASP) TESTER 


This program (asp2) displays a menu which enables the user 
to select one of the following: 

• Request a TEI 

• Discontinue use of randomly selected TEIs 

• Simulate two subscribers with the same TEI 

• Discontinue use of all TEIs 

This program is intended to be run against sample program 1 
so that you can see the Multi-Link LAPD sample program in 
action. For this reason, the startup() routine sets up the 
program to run on Port B, so that the two programs can be run 
against each other on a Dual Port machine. 

However, this program can be used as an independent test in 
an actual test environment. To use the program on Port A, or 
on a single port Chameleon, simply change the port selection 
in the startup routine. 

In this program, the following sequence occurs: 

• 1T»e Front End Processor (FEP) is initialized 

• A loop is entered that assigns a pseudo-random Rl value 
to each link. This value is made up of the link number in 
the MSB and a random number in the LSB. This 
accomplishes two things: 

^ Each Rl is guaranteed to be unique without a 
second loop to verify it 

^ It gives each Rl a tag so the user can more easily 
track the results of a test run. 


The User 

Interface A selection menu is printed on the upper part of the screen. 

The ’getch( stdvt)’ call scans the keyboard for any key 
stroke. Thelower part of the screen has two fields, the most 
recent user selection is described in the upper one, and the 
lower field describes the latest TEI assignment, denial, or 
removal. 
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#include <std1o.h> 

#include <cham.h> 

#include <ctype.h> 

#1nc1ude <fcntl .h> 

#inc1ude <init.h> 

#1nclude <video.h> 

#def ine T201 30 

extern Int rxlen; /*this is where receive puts the message length*/ 
char rmes[260] , tmesCS] , 1 nk_ri [64] ; 

/^Character arrays are used for storing the messages because it is easier to see what is being 
done to interpret the message and make aresponse.*/ 

main() 

{ 

int reti.lnkno; 

reti»startup(); /•call the startup routine*/ 

If(reti) /*1f any problems, quit*/ 
exit(O); 

/*while all the links are still disabled, setup the layer 2 parameters*/ 

reti=s_t200(0); 

reti»s_t203(0); 

* /*tiroers t200,t203 disabled to reduce irelevent traffic*/ * 

peti«s_n200(3); 
reti»sln201(260); 
ret 1 »set_wi ndow( 3 ) ; 

/*initialize the xmit message array, this will be used for id messages.*/ 
tmes[0]»15; 
tmesCl]-0; 
tmes[2]-0; 

/* setup 1 link for broadcast management procedures*/ 

reti=set_link(0); 
reti *set_sapi ( 63 ) ; 
reti*set_tei(127) ; 

/* go do the ASP test until the user wants to quit */ 
asptesO; 

/* go undo everything before simulation is stopped */ 
shut_down( ) ; 


} 


startup( ) 
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{ 

int rets; 

/♦attempt to start the FEP on port B and return the results. Setup is 
DTE simulation, subscriber, NRZ encoding, 16000 BPS. ♦/ 

rets=setport( PORTS ) ; /•run this program on port b^/ 
return(initpl( 1,1,0, 16000L)); 

} 

asptes( ) 

{ 

int rets,rivall; 

char lnkno,ansiier, tei ,teslnk,act_flag,quit_flag; 

/♦ set up RI value table ♦/ 

for(lnkno=l;lnkno<64; lnkno++) 
lnk_ri[lnkno]=6+2^1nkno; 

/♦list user selections^/ 
print_men( ) ; 

quit_flag=l; 

while(quit flag) /•loop until quit selected by user*/ 

{ 


answer=toupper(getch(__stdvt) ) ;/^get user command ♦/ 

rets=recei ve(&rmes[0] ) ; 
if(pxlen)/*if message received^/ 

{ 

pets*interp( );/*see what kind^/ 
tei={ rmes[6]&0xfe)»l; 
xyplot(5, 12) ; 
switch( rets) 

{ 

case 0; /♦message does not concern us*/ 
break; 

case l:/^tei assigned message^/ 

printfCTEI %6 assigned to link %d \n" , tei , Inkno) ; 

set_l ink(lnkno) ; 

set_sapi(0); 

set_tei(tei ); 

set_link(0); 

break; 

case 2: /•tei denied message^/ 

printfCTEI %d denied for link %d \n" , tei , Inkno) ; 

break; 

case 3: /♦id check message^/ 

lnkno=srch_lnk(265, tei ) ; 
if ( 1 (lnkno<0) ) 

{ 

tffles[l]=lnkno: 
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tmes[2]=lnk_ri[1nkno] ; 

tmes[33=6; 

tmes[4]={tei<<l)+l; 

settimer(0,500) ; /♦ if fep busy, keep trying 1/2 sec*/ 
rets=l; 

whi1e( rets&&timer(0) ) 
rets=trui(&troes[0],5) ; 

/•if user selection 0, fake 2 users on same tei^/ 
if{act flag==l) 

“{ 

tmes[l]=0; 
tmes[2]=lnk_ri[0]; 
tmes[3]=6; 
tmes[4]=( tei«l)+l; 

settimer{0 ,500) ; /♦ if fep busy, keep trying 1/2 sec*/ 
rets=l; 

while( rets&&tiiner(0)) 
rets=trui(&tmes[0],5) ; 
act flag^O; 

} 

} 

break; 

case 4:/^tei removed message*/ 

printf("TEI Xd removed \n",tei); 

set_l ink(srch_lnk(255, tei ) ) ; 
if(getjink()>0) 

sevtei<255); 

set_link(0); 

break; 

} 

} 

if ( (answer>='A* )&&(an$wer<~'H* ) ) 

{ 

xyplot(5,10); 
switch (answer) 

{ 

case * A* :/*request any tei*/ 
lnkno=get_f reel ink( ) ; 
tmes[13= (lnkno<0? 90:lnkno); 
tmes[23*{lnkno<0? 90: lnk_ri[lnkno3) ; 
tmes[33=l; 
tmes[43=256; 

printf( “requesting any tei for link %d \n“ ,tmes[l3) ; 

settimer(0,500) ; /* if fep busy, keep trying 1/2 sec*/ 
rets=l; 

while( rets&&timer(0)) 
rets=trui(&tmes[03,5) ; 
break; 

case 'B* :/*request specific tei*/ 
for(tei=64;tei<127;tei*»"‘‘) 

{ 

if(srch_lnk(255,tei )<0) 
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break; 

} 

lnkno=get_f reel ink ( ) ; 

tmes[l]= (lnkno<0? 90:lnkno); 

tmesC2]=(lnkno<0? 90; lnk_ri[lnkno]) ; 

tinesC3]=l; 

tmes[4]=(tei<<l)+l; 

printf( "requesting tei Xd for link \n" ,tei , tmes[l]) ; 

settimer(0,500) ; /• if fep busy, keep trying 1/2 sec*/ 
rets^l; 

while( rets&&tinier(0) ) 
rets=trui(&tnies[0] ,5) ; 
break; 

case 'C’ : A*requesV an existing tei*/ 
f or( tei ~ 126 ; tei >63 ; tei -- ) 

{ 

if {srch_lnk(256.tei )>=0) 
break; 

} 

lnkno=get_f reel ink( ) ; 

tmesCl]* (lnkno<0? 90:lnkno); 

tmesC2]={lnkno<0? 90: lnkjri[lnkno]) ; 

tffles[3]=l; 

tmesC4]=(tei<<l)+l; 

printf ("requesting existing tei %d for link %d \n" , tei , Inkno) ; 

settimer(0,500) ; /• if fep busy, keep trying 1/2 sec*/ 
rets*l; 

wh i 1 e( rets&&t ime r ( 0 ) ) 
rets»trui(&tmes[0],5) ; 
break; 

case *0* :/*siinulate 2 users with same tei*/ 
act_flag=l; 

printf("Next ID check will get 2 different responsesXn" ) ; 
break; 

case 'E’:/*kill 1 tei*/ 

for( tei =126; tei >63; tei — ) 

{ 

lnkno=srch_lnk(255,tei ) ; 
if (lnkno>=0) 
break; 

} 

if(lnkno<0) 

printf{"No TEI’s assigned 
else 

{ 

printf{"TEI Xd no longer in use 
set_l ink( Inkno) ; 
set_tei{255); 
set link(O); 

} 

break; 


\n"); 

\n",tei); 
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case ’F’ :/• kill all TEI's*/ 

for( lnkno=l ; 1 nkno<64; 1nkno++) 

{ 

set_l ink{ Inkno) ; 
set tei(256); 

} 

printf('*An TEI's no longer in use \n"); 

set_l ink(O) ; 

break; 

case *G': /♦stop test*/ 
quit_flag=0; 
break; 

case 'H': /• print help menu*/ 
print_raen( ) ; 

> 

} 

} 

} 

xyplot (xpos, ypos) 
int xpos, ypos; 

{ 

printf ( "\033[lCd;%df " , ypos. xpos); 
fflush (stdout); 

} . • ■ 

dear $creen() 

{ 

printf ("\033C2J"); 
fflush (stdout); 

} 

print men() 

{ 

clear_screen( ) ; 

printf('*A - request any TEIXn"); 
printf ("B - request specific TEI\n”); 
printf ("C - request a TEI that is in useNn”); 
printf ("0 - simulate 2 users with same TEINn”); 
printfCE - stop using a TEI\n"); 
printf("F - stop using all TEI’sVn"); 
printf ("G - stop test\n**); 
printf ("H - reprint screenXn"); 
xyplot(5,10); 

} 

1nterp( ) 

{ 

int rets; 


TEKELEC 


B. 11-72 


Version 2.5 





Chameleon 32 C Manual 


App. B.11: Multi-Link LAPD Library 


/♦return 0 if message not from link 0 ,not a UI frame, or not ASP 
entity id code*/ 

if (get_rlink( ) | | (get^rxstat( )&3) 1 | rmes[2]! =15) 
return{0) ; 

switch(rmes[5]) 

{ 

case 2: /♦id assigned*/ 
rets=l; 
break; 

case 3: /•id denied*/ 
rets=2; 
break; 

case 4: /•id check*/ 
rets=3; 
break; 

case 6: /•id removed*/ 
rets=4; 
break; . 

default: rets=0; 

} 

return(rets); 

} 

retmes(niestyp,ai ) 
char .inestyp,ai ; 

{ 

int rets; 

/• send return message generated by inserting new message type and 
ai values into the last received message.*/ 

rmes[5]=mestyp; 

rmes[6]=(ai«l)+l; 

settimer(0,500} ; /* if fep busy, keep trying 1/2 sec*/ 
rets=l; 

while( rets&&timer(0)) 
rets=trui(&rmes[2],5) ; 

} 

shut_down( ) 

{ 

int rets; 
char Inkno; 

for(lnkno=l;lnkno<64; lnkno'*-+) 

{ 

rets=set_l ink( Inkno); 
if (status( )>0 && status()<9) 
rets=slof ( ) ; 

} 

} 
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B.12 V.120 LIBRARY 


The V.120 library is an optional C library which must be 
purchased in addition to the Chameleon 32 C Development 
System. It supports a total of 64 independent links and 
adheres to the following V.120 protocol requirements: 

• The C/R bit is set to 0 for all commands, and to 1 for all 
responses, regardless of the sending station 

• 1-Frames can be command or response frames 

• When a command reject (CMDR) occurs the link is 
automatically restarted 

The library is named Iibv120.a and is located in the a:\lib 
directory of the hard disk. 


V.120 Address The format of the V.120 address field can be viewed as a 

single 13-bit Logical Link Identifier (LLI) field or as two 
separate fields (LLIO and LLM). This is shown as follows: 


87654321 Bits 


Octet 2 (Address Octet 1) 


Octet 2 (Address Octet 1) 


The LLIO is the high order 6 bits of the LLI. The LLI1 is the 
low order 7 bits of the LLI. The LLI is a concatenation of the 
LLIO field with the LLI1 field. The LLI can take on values in the 
range 0-8191, with the following reserved values: 


LLIO 

C/R 

E 

A 

0 



E 

LLI1 


A 



1 


LLI 

(In Decimal) 

FUNCTION 

0 

In-channei signaling 

1 -255 

Reserved for future standardization 

256 

Default LU 

257-2047 

For LLI assignment 

2048-8190 

Reserved for future standardization 

8191 

In-channel layer management 


LLI Values 
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Link Selection 


Frame Status 
Word 


EAO is the octet 2 address extension bit, which is set to 0. 
EA1 is the octet 3 address extension bit, which is set to 1 for 
two octet address field. 

With the V.120 library, you select one of the 64 links {0 - 63) 
using the set link function. You then assign the link an LLI 
with the set_Iir function as a single decimal value as shown in 
the figure on the previous page. Ail links default to state 9, 
disabled. 

When you select a link using set link, you can then use the 
other library functions to set the link on (slon), set the link off 
(slof), and transmit and receive messages. 


A two-byte frame status (frstat) which is attached at the 
beginning of each received message provides access to the 
following information: 

• Link number over which message was received 

• Frame type 

• Command or response frame 

• Poll/Final bit value 

The get rxstat function returns the low order byte of frstat. 

The get rlink function returns the high order byte of frstat 
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Functions 


The V.120 library provides the functions listed below. Also 
refer to the common functions and error codes described in 
Appendix B.1. 


get_freelink() B.12-4 

get fwaiting B.12-5 

get link() B.12-6 

get_lli() B.12-7 

get Inklli B.12-8 

get meswaiting B.12-9 

get rlink() B.12-10 

get_rxstat{) B.12-11 

get_sconfig () B.12- 12 

get ^window B. 12-1 3 

initpl . B.12-14 

link_stat B.12-15 

receive B.12-16 

S_n200 B.12-17 

s__n201 B.12-18 

S__t200 B.12-19 

S_t203 B.12-20 

set_link B. 12-21 

set_lli B. 12-22 

set__sconfig B. 12-23 

set_window B. 12-24 

setfig B.12-25 

slof 0 B.12-26 

Sion 0 B. 12-27 

srch_lnk B. 12-28 

start Sim B. 12-29 

statusO B. 12-30 

trans B. 12-31 

transmit B. 12-32 

trans resp B. 12-33 

trui B. 12-34 

trxcni B. 12-35 

trxidc B.12-36 

trxidr B. 12-37 

trxmi B.12-38 


TEKELEC 


8.1 2-3 


Version 2.4 





Chameleon 32 C Manual 


App. B.12: V.120 Library 


get freelInkO 


Declaration int get freelink() 


Description This function gets the number of the first disabled link. 


Returns 


0-63 Disabled link number 

-1 No free links available 

-2 initpt not performed 
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get__fwaiting 

Declaration 


Range 

Description 


Returns 


int get fwaiting (Inkn) 
char liiRh; 


Inkn 0-63 


This function gets the number of l-frames waiting to be 
transmitted on link Inkn. 


0-7 Number of l-frames waiting to be sent by link Inkn 
See also the global error codes on page B.1-1. 
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get llnk{) 

Declaration 


Description 


Returns 


int get link() 


This function gets the number of the link which is currently 
under user control. 


0-63 Current link number 

-1 initpt not performed 

See also the global error codes on page 
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get_lli() 

Declaration 


Description 


Returns 


int get lli() 

This function gets the LLI of the link currently under user 
control. 

0 - OxI FFF LLI of current link 
-1 initpl not performed 

See also the global error codes on page 
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Declaration 


Range 

Description 

Returns 


App.B.12: V. 120 Library 
a — 


int get Inklli (Inkn) 
char IriRh; 


Inkn 0-63 


This function gets the LLI value for link Inkn. 


0 - 0x1 FFF LLI value assigned to link n 
> 0x1 FFF Link Inkn Is disabled 

See also the global error codes on page B.1-1. 
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get meswaiting 


Declaration int get meswaiting {) 


Description This function gets the number of messages waiting to be 

received from the Front End Processor (FEP). 


Note 


An additional received message is buffered by the library. 


Returns 0-32 Number of messages waiting to be received from 

the FEP 


See also the global error codes on page 
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get rlInkO 

Declaration 


Description 


Returns 


int get rlink() 


This function gets the number of the link which sent the last 
received message. This is the high order byte of the frame 
status word frstat passed by the FEP, 


0-63 Current link number 

-1 No messages received yet 

-2 initpl not performed 

See also the global error codes on page B.1-1. 
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get rxstatO 

Declaration char get rxstat() 


Description This function gets the low order byte of the frame status word 

frstat, which contains the frame type etc. for the last received 
message. 


Returns 


0 - 0xC3 frstat value (interpreted as shown below) 

OxFF No messages received yet 

OxFE initpt not performed 

See also the global error codes on page B.1-1. 


7 

6 

5 

D 


2 

1 

0 


High bit/low bit 


00 = Ul frame 

01 = XID frame 

10 * l-frame 

11 = FRMR 


Reserved 


0 = Command frame 

1 = Response frame 


0 = Poll/Final bit clear 

1 = Poll/Final bit set 


Examples 


0x41 Non-final XID response 

0x02 l-frame command 

0xC3 Final FRMR response 
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get sconfig {) 

Declaration int get sconfig () 


Description This function returns a copy of the current control configuration 

byte, which can be interpreted as shown in the figure below. 


76543210 


Bit 


Reserved 


Interframe Fill 

0 = Set interframe fill to value 7E 

1 = Set interframe fill to value FF 


Reserved 


Status Changing Frames 

0 = Poll normalTSet poll bit normal on status changing 

frames SABM(E) and DISC.) 

1 = Poll set (Set poll bit on status changing frames 

SABM(E) and DISC) 


SABM(E) Response 

0 = UA only. Stop generating SABM(E) collisions. 

1 = UAancfSABM(E). Generate SABM(E) collisions. 


XID Poll Bit 

00 =: No XID frames polled. 

01 = Poll only XID frames without l-fields. 

10 = Poll only XID frames with l-fields. 

1 1 = Poll all XID frames 


XID Exchange 

0 = Stop transmitting XID's on T203 timeout. 

1 = Transmit XID command on T203 timeout 
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get ^window 

Declaration 


Range 

Description 


Returns 


int get window (Inkn) 
char IriRh; 


Inkn 0-63 


This function gets the number of outstanding l-frames on link 
number inkn. 


0-7 Number of unacknowledged l-frames of link Inkn 
See also the global error codes on page B.1-1. 
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initpl 

Declaration 


Description 


Note 


Ranges 


Returns 


int initpl (interface, sta, encode, bitrt) 
int interface, sta, encode; 
long bitrt; 


initpl loads the Front End Process (FEP) code for the 
selected library and starts simulation. Predefined values exist 
in mlklib.h to aid in setting up the call to this function, sta is 
the station type and selects the initial sense of the 
command/response bit. The library permits reselection of the 
station type at any time, encode selects the physical data 
encoding, bitrt sets the data rate when simulating a DCE 
device. 


This function is identical to and Interchangeable with the 
start__sim function, it is included to provide downward 
compatibility with the single link LAPD library. 


interface 0 V-type interface (DCE) 

1 V-type interface (DTE) 

2 ISDN interface 


sta 0 V.120 

encode 0 NRZ 

1 NRZI 


bitrt Any long integer value from 50 - 64000. 


See the global error codes on page B.1-1. 
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link stat 


Declaration int link stat(n) 

char n; 


Range 

Description 

Returns 


n 0-63 

This function gets the current state of link n. 

0-9 Current state of link (see table below) 

See also the global error codes on page B.1-1. 


STATE 

LINK STATUS 

0 

Link Disconnected 

1 

Link Connection Requested 

2 

Frame Rejected 

3 

Disconnect Requested 

4 

Information Transfer 

5 

Local Station Busy 

6 

Remote Station Busy 

7 

Local and Remote Station Busy 

8 

Remote Station not Responding 

9 

Link Disabled 
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receive 


Declaration 


Description 


int receive{dest addr) 
char *dest addrT 


This function receives a message from the FEP by performing 
the following tasks: 

• It polls the FEP to see if any received messages are 
available 

• It transfers the message contents to the user defined 
buffer pointed to by dest__addr 

• The total length of the message (including the frame 
status bytes frstat) is placed in the global variable rxlen 

The frstat word is accessible by calling get rlink and 

get rxstat so that you can interpret and respond to a 

message quickly. The frstat bytes are attached to the 
beginning of each received message so that several 
messages rhay be received, sorted, interpreted, and 
individual responses made. 

it is up to the user to assure that the destination buffer is long 
enough to contain the message. Generally, a length equal to 
N201 + 2 is adequate. 

I I 
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s n200 


Declaration 


Range 

Description 

Returns 


int s n200 (val) 
int vaT; 


val 1 - 255 


This function sets the maximum number of retries (N200). 


0 Successful 

See also global error codes on page B.1-1. 
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s n201 


Declaration 


Range 

Description 

Returns 


int s n201 (val) 
int vaT; 


val 1 - 512 


This function sets the maximum length for an l-frame (N201 ). 


0 Successful 

See also global error codes on page 6.1-1. 
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s t200 


Declaration 


Range 


Description 


Returns 


int s 1200 (val) 
int val; 


val 0 - 255 


This function sets the time allowed for the remote station to 
respond (T200). Setting this value to 0 disables the T200 
timer. 


0 Successful 

See also global error codes on page 
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s t203 


Declaration 


Range 


Description 


Returns 


int s t203 (val) 
int vaT; 


val 0 - 255 


This function sets the maximum time between frames (T203). 
On time out, a polled RR or XID command is transmitted, 
depending on the configuration selection. Setting this value to 
0 disables the T203 timer. 


0 Successful 

See also global error codes on page B.1-1. 
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set link 


Declaration 

int set link(n) 
char n; 

Range 

n 0-63 

Description 

This function puts link n under user control. Only one link at a 
time can be under user control. Initpl must be performed 
prior to this function. 

Returns 

0 Successful 


-1 Parameter out of range 
-2 initpl not performed 
' -3 Timeout 

See also the global error codes on page B.1-1. 
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set sconfig 


Declaration int set sconfig (byte) 

int byte; 


Description This function sets the value of the control configuration byte, 

Interpreted as shown in the figure below. 


76543210 


Bit 


Reserved 


Interframe Rll 

0 = Set interframe fill to value 7E 

1 = Set interframe fill to value FF 


Reserved 


Status Changing Frames 

0 = Poll normalTSet poll bit normal on status changing 

frames SABM(E) and DISC) 

1 = Poll set (Set poll bit on status changing frames 

SABM(E) and DISC.) 


SABM(E) Response 

0 = UAonly. Stop generating SABM(E) collisions. 

1 s UAanaSABM(l). Generate SABM(E) collisions. 


XID Poll Bit 

00 = No XID frames polled. 

01 = Poll only XID frames without l-fields. 

10 = Poll only XID frames with l-fields. 

11 = Poll all XID frames 


XID Exchange 

0 = Stop transmitting XID's on T203 timeout. 

1 = Transmit XID command on T203 timeout. 


Returns 0 Successful 

See also global error codes on page B.1-1. 
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set Hi 


Declaration 


Range 


Description 


Returns 


int set_lli{val) 
int val; 


val 0x00 - OxFFFF hex 

A value > 0x1 FFF disables the link 


This function sets the LLI (Logical Link Identifier) value for the 
link under user control. 


0 Successful 
-1 Parameter out of range 
-2 initpl not performed 
-3 Timeout 

See also the global error codes on page 
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set ^window 

Declaration 

Range 

Description 

Note 

Returns 


int set ^window (val) 

int val; 


val 1-7 


This function sets the maximum number of outstanding frames 
on each link. 

The total of outstanding frames + the number of frames 
passed to the FEP waiting to be transmitted + the number of 
messages over 16 bytes long waiting to be received from the 
FEP may not exceed 80. 


0 Successful 

See also global error codes on page B.1-1. 
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setfig 

Declaration 


Range 


Description 

Returns 


int setfig (flag) 
int flag; 


flag 0 0x7E fill 

1 OxFF fill 


This function selects an interframe fill pattern. 


0 Successful 

See also global error codes on page 
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slot 0 

Declaration 


Description 


Returns 


int slof 0 


This function sends a DISC and waits for a UA frame. This is 
equivalent to the CCITT primitive dl release. 


0 Successful 

Also see global error codes on page B.1-1. 


Tekelec 


8.12-26 


Version 2.4 





Chameleon 32 C Manual 


App. B. 1 2: V. 1 20 Library 


slon 0 

Declaration 


Description 


Returns 


int slon () 


This function sends a SABME and waits for a UA frame. This 
is equivalent to the CCITT primitive dl establish. 


0 Successful 

Also see global error codes on page B.1-1. 
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srch Ink 


Declaration 


Description 


Returns 


int srch Ink(lli) 
int Hi; 


This function returns the number of highest link matching the 
specified LLI. 


0-63 Number of highest link matching parameters 

-1 No match found 

See also the global error codes on page 
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Start slm 


Declaration 


Description 


Note 


Ranges 


Returns 


int start sim (interface, sta, encode, bitrt) 
int interface, sta, encode; 
long bitrt; 


start sim loads the Front End Process (FEP) code for the 
selecfed library and starts simulation. Predefined values exist 
in mlkiib.h to aid in setting up the call to this function, sta is 
the station type and selects the initial sense of the 
command/response bit. The library permits reselection of the 
station type at any time, encode selects the physical data 
encoding, bitrt sets the data rate when simulating a DCE 
device. 


This function is identical to and interchangeable with the initpl 
function. The initpl function is provided for downward 
compatibility with the single link LAPD library. 


interface 0 V-type interface (DCE) 

1 V-type interface (DTE) 

2 ISDN interface 


sta 

encode 


0 

1 


V.120 

NRZ 

NRZI 


bitrt 


Any long integer value from 50 - 64000. 


See the global error codes on page B.1-1. 
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statusO 


Declaration 


Description 

Returns 


int statusO 

This function gets the current state of link under user control. 

0-9 Current state of link (see table below) 

See also the global error codes on page 


STATE 

LINK STATUS 

0 

Link Disconnected 

1 

Link Connection Requested 

2 

Frame Rejected 

3 

Disconnect Requested 

4 

Information Transfer 

5 

Local Station Busy 

6 

Remote Station Busy 

7 

Local and Remote Station Busy 

8 

Remote Station not Responding 

9 

Link Disabled 
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trans 

Declaration 


Description 


Returns 


int trans (frame, address, len) 
int frame, len; 
char "address; 


This functions transmits a frame as follows: 
frame selects type of frame to transmit: 


0x80 

l-frame 

Sequenced (numbered) 
l-frame 

0x81 

Ul 

Unnumbered l-frame 
(NSI) 

0x82 

XIDC 

XID command frame 

0x83 

XIDR 

XID response frame 

0x84 

RESP FRAME 

FRAME response 


address is a pointer to the first byte of the message to be 
transmitted. 

ien is the actual length of the message to be transmitted. 
There are two restrictions on the message length: 

• l-frames must not exceed the value set in N201 

• The total length of the frame cannot exceed 512 bytes 


0 Successful 

Also see global error codes on page B.1-1. 
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transmit 


Declaration 


Description 


Note 


Returns 


int transmit (xioc, xlen) 
char *xloc; 
int xlen; 


This function transmits a message in a sequenced (numbered) 
l-frame. 

xioc is a pointer to the first byte of the message to be 
transmitted. 

xlen is the actual length of the message to be transmitted. 
The length of an l-frame must not exceed the value set in 
N201. 


The transmit function is provided for user convenience. If 
extremely high data rates are required, the trans function 
should be used, as it is somewhat faster. 


0 Successful 

Also see global error codes on page B.1-1. 
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trans resp 


Declaration 


Description 


Note 


Returns 


int trans resp (xioc, xlen) 

char *xloc; 
int xlen; 


This function transmits a message in a sequenced (numbered) 
l-frame response. 

xioc is a pointer to the first byte of the message to be 
transmitted. 

xlen is the actual length of the message to be transmitted. 
The length of an l-frame must not be more than the value set 
in N201. 


The trans resp function is provided for user convenience. If 
extremely“high data rates are required, the trans function 
should be used, as it is somewhat faster. 


0 Successful 

Also see global error codes on page B.1-1. 
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trui 


Declaration 


Description 


Note 


Returns 


int trui (xioc, xlen) 
char ’*xloc; 
int xlen; 


Transmit a message in an unnumbered l-frame (Ul frame). 

xioc is a pointer to the first byte of the message to be 
transmitted. 

xien is the actual length of the message to be transmitted. 
The lenght of an l-frame must not exceed the value set in 
N201. 


The trui function is provided for user convenience. If extremely 
high data rates are required, the trans function should be 
used, as it is somewhat faster. 


0 Successful 

Also see global error codes on page B.1-1. 
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trxcni 


Declaration 


Description 


Returns 


int trxcni () 


This function transmits an XI D command frame with no data 
field. 


0 Successful 

See also global error codes on page 


I 
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trxidc 


Declaration 


Description 


Note 


Returns 


int trxidc (xioc, xlen) 
char *xloc; 
int xlen; 


This function transmits a message in an XID command frame. 

xIoc is a pointer to the first byte of the message to be 
transmitted. 

xlen is the actual length of the message to be transmitted. 
The total length of the frame must not exceed 512 bytes 


The trxidc function is provided for user convenience. If 
extremely high data rates are required, the trarts function 
should be used, as it is somewhat faster. 


0 Successful 

Also see global error codes on page B.1-1. 
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Description 


Note 


Returns 


App. B.12: V.120 Library 


int trxidr (xioc, xlen) 
char *xloc; 
int xlen; 


Transmit a message in an XID response frame. 

xioc is a pointer to the first byte of the message to be 
transmitted. 

xlen is the actual length of the message to be transmitted. 
The total length of the frame must not exceed 512 bytes. 


The trxidc function is provided for user convenience. If 
extremely high data rates are required, the trans function 
should be used, as it is somewhat faster. 


0 Successful 

Also see global error codes on page B.1-1. 
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trxrni 

Declaration int trxrni () 

Description This function transmits an XI D response frame with no data 

field. 

Returns 0 Successful 

See also global error codes on page 
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Sample 

Programs 


Makefile 


Testl.c 


The following are two sample SIMP/L V.120 programs which 
can be run against each other on a Dual Port Chameleon 32. 
Program testl.c uses Port B; test2.c uses Port A. The two 
programs interact as follows: 

• Testi sets up 64 links and randomly transmits on one of 
the links. 

• Test2 receives the message and returns the message on 
the same link as was received. 

The program terminates when the letter Q is pressed, or the 
link is lost. 


The following is the makefile for the two sample programs: 

tests : testi test2 
testi : testi. o 

cc ~o testi testi.o -1vi20 
test2 : test2.o 

cc -o test2 test2.o -lvl20 


The sample program testi .c is as follows: 

finclude <std1o.ti> 

#inc1ude <ciiaa.h> 

#1nc1ude <ctype.h> 

#include <fcntl.h> 

#inc1ude <1nit.h> 

#inc1ude <video.li> 

char tasg[48],niS9[48]; 

■ainO 

{ 

Char Insit, teapc, answer, *tadr,*radr; 

extern char; 

extern int rxlen; 

int resu1t,teap1; 

long int count; 

printf{*C prograw started. \n"); 

tadr=&twsg[0]; 

radr=^&nisg[0]; 

s_start(); 

/mmmmm aalce and display transwit Message 
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for(insit=0; iiisit<=16; insit-i^) 

Uisg[insit] == 15 ~ insit; 

printf ("transmit message = •); 
for(insit=0; insit<=16;insit-*-<-) 
printf(* XOji • ,tiisg[insit]) ; 
printf(*\n*); 

/•###« ijo fraae level setup ••••♦/ 

resul t=set_«od( 1 ) ; 
result=s_t200(0); 
resul t=s_t203(0); 
resul t=s_n201 ( 20 ) ; 
resul t«set_«i ndo«( 3 ) ; 

/•••♦• setup 111 for 64 links ♦♦♦•♦/ 

f or( ; ; ) 

{ 

te«pi-get_f reel ink( ) ; 
if(teapi<0) 
break; 

printf(*free link = IdVn" .teapi ) ; 
resul t=set_l ink{teapi ); 
resul t>set_l 1 i ( teap 1*3) ; 

} 

ab11e(status()<4); 
result=set_link(2) ; 
resul t-trans( 0x80, tadr, 16); 
counted; 

resul t=get_l ink( ) ; 
clear_screen( ); 

printf ("Current link is Xd\n" .result); 

/•*♦•* send and receive until link state is less than 4 
****** or user types "Q* *♦♦♦/ 

for(;;) 

{ 


answer • toupper(getch(_stdvt)); 
if((status()<4)| |(answer==*Q* )) 
break; 

resul t=receive( radr) ; 
if(rxlen>0) 

{ 


Tekelec 


B. 12-40 


Version 2.5 





Chameleon 32 C Manual 


App. B.12: V. 120 Library 


xyp]ot(5,5); 

printf( "received nessage = *); 

for( insit=0; insiKrxlen; insit-M- ) 

printf(* XOx " , nisg[insit]) ; 
printfCXn-); 

printf ("Reclink = Xd, frstat = Xx 
\n* ,get_rl ink( ) ,get_rxstat( ) ) ; 

select a link at randoM and, if it is not busy, send a aessage */ 

teapc=63^rand( ); 
resu1t=set_link(teapc); 
if (status( )<5) 

result=trans(0x80,tadr, 16); 
count-i-^ ; 

printf{ "That's Xld.Xn", count); 

} 


/••••♦ if link still connected, disconnect it, then exit ♦♦♦♦♦/ 

if (status( )>0) 

{ 

result=slof(); 

printf("slof result X0d\n", result); 
«hile(status()>l); 

} 

} 

xyplot (xpos, ypos) 
int xpos, ypos; 

{ 

printf ( "XOaafXd ;Xdf • ,ypos , xpos ) ; 
f flush (stdout); 

} 

clear_screen{ ) 

{ 

printf CNOaaCaj*); 
fflusti (stdout): 

} 

s_start( ) 

{ 

int rets,ret2; 

rets=setport( PORTS ) ; 
printf ("Trying to start PI"); 
rets= initpl( 1,1,0, 6400L) ; 
printf (• result = X0x\n", rets) ; 

} 
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Test2.c The sample program test2.c is as follows: 


#inc1ucle <stdio.h> 

#include <ctia«.h> 
finclude <ctype.h> 

#1nclude <fcntl.h> 

#1nclude <1nit.h> 

#1nc1ude <video.h> 

/* sake buffers for tx and rx Messages 
char tMsg[48].nisg[48]; 

■a1n() 

{ 

Char 1ns1t,ans»er,^tadr,^radr; 
extern char; 
extern int rxlen; 

Int result,teap1; 
long int count; 

pr1ntf(*C program started.Vn*); 
tadr=&Uisg[0]; 
radr=&nisg[0]; 
s_start{ ) ; 

/•♦••• Make and display transait Message 

for( 1nsit-0; 1nsit<=16; insit^) 

tMsg[1nsit] = insit; 

printf(*transMit Message = *); 
for(insit=0;insit<=16;insit'M*) 
printf(* XOx ”,tasg[insit]) ; 
printfC\n»); 

do frame level setup ••••♦/ 

result=set_Mod( 1) ; 
resul t=s_t200{ 0 ) ; 
result=s_t203(0); 
resul t=s_n20 1(20); 
result=set_«indo«(3) ; 

setup Hi for 64 links and set them on •••••/ 

for(;;) 

{ 

teMpi-get_f reel ink( ) ; 
if ( teMpKO) 

. break; 

printf("free link = Xd\n", tempi); 
resul t=set_l ink( tempi ) ; 
result=set_lli( tempi *3); 
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result=slon( ) ; 

«hile(status( )<4); 

} 

test get link stats 

f o r ( teap 1 = 0 ; t eap 1<64 ; teap i ) 

{ 

result=link_stat(teBpi) ; 

printf(* link= Xd ",teapi); 

printf(* state = XdAn", result); 

resul t=9et_»indo«( teapi ) ; 

printf(* aindoa = Xd.\n”, result) ; 

result=get_faaiting( teapi ) ; 

printf(*f raaes to be sent = Xd.Xn", result); 

resul t=get_aes«aiting( ) ; 

printf(* aessages to be received = Xd.\n*, result); 
resul t=9et_lnkl 1 i ( teapi ) ; 
printf(* Hi = XdAn", result); 

} 

/••••• test link search function 
search 12 should return 4 
search 66 should return 22 
search 189 should return 63 
search 11 should return *not found* 

printf ("result of search 12 = XdXn* , result); 
resul t =s rch_l nk( 66 ) ; 

printf ("result of search 66 = Xd\n”, result); 
resul t=srch_l nk( 189 ) ; 

printf(" result of search 189 = Xd\n”, result); 
result=srch_lnk(ll); 

printf ("result of search 11 == Xd\n*, result); 

send and receive untill link state is less than 4 
or user types "Q" 

result=set_link(2); 
teapi =0; 
count-0; 

resul t=get_l ink( ) ; 
clear_screen( ); 

printf("Current link is Xd\n" , result) ; 

for(;;) 

{ 

answer = toupper(getch(_stdvt) ) ; 
if((status( )<4) I |(ansaer==*Q* )) 
break; 

resul t=receive( radr); 
if(rxlen>0) 

{ 

xyp1ot(5,5); 

printf (’received Message = *): 
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for( insit=0; ins1t<rxlen; insit++) 

priiitf{* XOx ",nflisg[ins-it]); 
printf ("Xn"); 

printf{ "Reel ink = Xd, frstat = Xx 
\n" ,get_rl ink( ) ,get_rxstat( ) ) ; 

resul t=set_l ink(get_rl ink( ) ) ; 
if (status( )<5) 
result==trans(0x80,tadr» 15); 
count'M*; 

printf{ "That's Xld.Xn" .count) ; 

> 

} 

/••••• if link still connected, disconnect it, then exit •••••/ 

if (status( )>0) 

{ 

result=slof( ); 

printf("slof result XOdXn", result); 

«hile(status( )>1) ; 

} 

} 

xyplot (xpos, ypos) 
int xpos, ypos; 

{ 

printf (*\033CXd;Zdf* , ypos, xpos); 
f flush (stdout); 

) 

clear screen() 

{ 

printf ("XOaaCZJ"); 
f flush (stdout); 

} 


s_start( ) 

{ 

int rets,ret2; 

rets=setport( PORTA) ; 
printf("Trying to start PI"); 
rets= initpl(0,0,0,6400L); 
printf (" result = XOxXn" , rets) ; 
> 
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B.13 MULTI-LINK HDLC C LIBRARY 


Introduction The Multi-Link HDLC C Library (libmhdlc.a) is located In the \lib 

directory. It can be used only on a Dual Port Chameleon 32. 

The Multi-Link HDLC library enables a Dual Port Chameleon 
32 to simulate two links using the HDLC protocol. With the 
Multi-Link HDLC library, each port is configured as a 
permanent virtual circuit, providing two links for testing a multi- 
path network. 


Unk A 


Port A 


LinkB 


Port B 



■ • 
■■ 
■■ 



Unk A 


LinkB 


Dual Port 
Chameleon 32 


The Multi-Link HDLC library is an enhanced version of the 
HDLC library described in Appendix B.3. The HDLC library 
provides single link simulation, whereas the Multi-Link HDLC 
library provides dual link simulation 
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Applications 


The library provides a high degree of flexibility while providing 
solutions to the problems of simulating an HDLC system with 
multiple physical links. The library provides functions for 
initializing both ports with the automatic layer 2 FEP software, 
establishing links, and transmitting, and receiving data on 
either port. 

Some applications of the library include: 

• Simulating a multi-circuit device by connecting the 
Chameleon to two Permanent Virtual Circuits (PVCs) of a 
multi-path packet switching network. 

• Testing a single circuit by inserting the Chameleon into 
the middle of a single circuit and running simulation in 
both directions to the devices on either end. This 
provides a divide and diagnose test to find a circuit fault. 

• Use the Chameleon as a emergency adaptor. This 
library was not intended for such an application; however, 
it is possible to use the Chameleon as an adaptor 
between two incompatible HDLC devices. 

For example, use the Chameleon between two DTE 
terminals or as a rate adaptor between two devices that 
run at different data rates. In this context, it is possible 
to connect an ISDN Basic Rate Interface to an ISDN 
Primary Rate Interface. 

• Use the Chameleon to compare two devices or 
networks. The Chameleon can be set to transmit in 
redundant mode so that the same data is transmitted 
over both ports. The responses of the two 
devices/networks can then be evaluated. 
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FUNCTION 

PAGE 

flush 

B.1 3-9 

flush_all 

B.1 3-10 

init a 

B.1 3-11 

init__b 

B.1 3-1 2 

initpl 

B.1 3-1 3 

mih ^flush 

B.1 3-1 4 

mih receive 

B.1 3-1 5 

mIh set n1 

B.1 3-1 6 

mih set n2 

B.1 3-1 7 

mih ^set net 

B.1 3-1 8 

mih set__sub 

B.1 3-1 9 

mih set ^t1 

B.1 3-20 

mih set___t2 

B.1 3-21 

mih set__window 

B.1 3-22 

mih slot 

B.1 3-23 

mih slon 

B.1 3-24 

mlh__status 

B.1 3-25 

mih trans 

B.1 3-26 

receive 

B.1 3-27 

set_n1 

B.1 3-28 

set__n2 

B.1 3-29 

set_net () 

B.1 3-30 

set__pat 

B.1 3-31 

set__ratio 

B.1 3-32 

set__t1 

B.1 3-33 

set__t2 

B.1 3-34 

set sub 0 

B.13-35 

set window 

B.1 3-36 

slofT) 

B.1 3-37 

Sion 0 

B.1 3-38 

status 0 

B.1 3-39 

transmit 

B.1 3-40 


Also refer to Appendix B.1 for a description of common library 
functions and error codes. 

Sample programs using the Multi-Link HDLC library are 
provided at the end of this section. 
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Simulator 

Initialization 


Note 


The library provides three functions for initializing the 
Charneleon ports to run the Multi-Link HDLC simulator. These 
functions are: 

initpt This function initializes both Ports A and B with 
identifical configuration parameters with a single 
call. For example, both ports are initialized as 
DCEs with a bit rate of 56000. For most testing 
applications, both ports will be the same. 

init a 

init^T) If the testing application requires that Port A and 
Port B configuration differ, each port can be 

initialized independently using the init a and 

init b functions. 

There are some unique applications for the 

init a()/init b()functions. Programs with an 

automatic send/receive/respond function can test 

themselves by temporarily inserting init a() and 

init b() calls and connecting the two ports together 
asTJCE and DTE, network and subscriber. 

it is also possible, using a fairly simple 
receive/resend program, to use the Chameleon 32 
as a data rate or side translator to link incompatible 
equipment such as two DCE devices or two 
devices with no common data rate selection. 

When configured as a DTE or for ISDN, timeout errors may 
occur when the Chameleon is configured for a data rate that is 
significantly higher than what is actually being received. This 
is more likely to occur when very long packets are being 
exchanged because the timeout interval is adjusted to the data 
rate to minimize delays. If unwarranted timeout errors occur 
consistently. Initialize the port using a lower data rate. 


Tekelec 


B.13-4 


Version 2.5 




Chameleon 32 C Manual 


Appendix B.13: Multi-Link HDLC Library 


Transmitting 

Data 


Global 

Variables 


There are two transmit functions in the library: 

transmit This function transmits a packet over a 

specified port. 

mih ^trans This function transmits a packet to a port 

depending on a specified distribution pattern 
which is defined using one of the following 
functions: 

• set ratio specifies the distribution 
pattern of the packets being transmitted 
over the two ports. The ratio can be set 
so that all, none, or a specified 
percentage of packets is transmitted 
over Port A or Port B. 

• set pat specifies a user-defined 

distriBution pattern if set ratio does not 

provide the distribution required by the 
testing application. 

Each time a call is made to mIh trans, the 
simulator determines over- which port to 
transmit the packet. 

mih ^transO should be used to transmit 

information packets only. Other packet types 
should be sent using the transmit() function. 


When the two physical ports are used for different Logical 
Channel Numbers (LCNs), it is important that the application 
has a means of determining which port will transmit the next 
packet. This can be determined using two global variables 
and a pointer: 

rec port This is a variable which Indicates which port 

provided the last received data packet: 

0 Port A 

1 Port B 

tpat ptr This counter is used by the function 

mih trans to determine which port will be 
use31o transmit the next packet. This counter 
is the offset into the pattern table pointed to 
by pat loc. 
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pat loc This is a pointer to the pattern table used by 

mih transO to determine how transmitted 
pacRets are to be distributed to Ports A and B. 

Reading the character located at ’“{pat loc + 

tpat ptr) provides a means of determining 
whicFf port will transmit the next packet. The 
possible values of the character are: 

1 Port A 

2 Port B 

0 End of pattern table 


The following program fragment demonstrates the use of 
these variables: 


cliar nextjport; 

aextj>ort » •(pat_loc + tpat^ptr); 

if (!next_port) /•If end of pattern flag •/ 
nextjport = •patloc; /• use start of pattern •/ 

svi tcii( nextjport ){ 

case 1: /• port A is next •/ 
tx_lcgn * lcgn_a; 
tx_lcn * lcn_a; 
tx_ps * ps_a-w-; 
tx_pr * pr_a; 
break; 

case 2: /• port B is next •/ 
tx_lcgn = lcgn_b; 
tx_lcn * lcn_b; 

tx_pr * pr_b; 
break; 

default : oh_oh_error( BAO^PATRN ) ; 

> 

The packet is then assembled using the tx components and 

transmitted using mIh trans(). 
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Reception 


When the Front End Processor (FEP) for either port receives a 
frame, the simulator automatically generates a response 
frame, if applicable. If an information frame is received, the 
packet is passed to a FIFO (first in-first out) message buffer 
and is given to the program by calling one of the following 
receive functions: 

receive This function causes the Chameleon to check 

the reception buffer of the specified port. 

mih receive This function checks both ports for received 

packets and returns one packet on each call, 
if one is available. It remembers which port 
provided the last packet, and gives preference 
to the other port on the next call. If the 
preferred port has no packet available, the 
other port is then queried. 

For example, assume three packets were 
received on Port A and one packet on Port B. 
If the current preferred port is A, successive 

calls to mIh receive will return packets in this 

order: 

Port A packet T 

Port B packet 1 

Port A packet 2 

Port A packet 3 

After Port A packet 2 is returned. Port B is 
queried, and since it has no packet available. 
Port A packet 3 is returned. 


With either receive function, the following occurs: 

• The packet is transferred from the message reception 
buffer to a user defined buffer 

• The global variable rxlen is set to the length of the 
received packet 

• If mih receive was called to receive the packet, it sets 
the global variable rec port to indicate from which port 
the packet was received" 
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Set Functions 


In applications where packets are transmitted in redundant 
mode by the remote device, receive{) should be used. This 
simplifies the process of comparing a packet from Port A with 
the same packet from Port B. 

In applications where packets are being distributed over both 
physical links by the remote unit, using mih receive{) makes 
it easier to quickly generate response packers and send them 
on the correct port. 

For applications where the Chameleon-32 is being used as a 
rate adapter, DTE/DTE or DCE/DCE translator, or an Interface 
translator (eg. V.35 to BRI), using recelve() provides a quick 
turnaround, as shown in the following program fragment: 


«h11e(l) { endless loop, there should be soae 

exit code included such as break if the 
'q* is typed or if the state of one 
link goes to 0. V 


receive (PORTIA, •buffer); 
if (rxlen) 

transait (PORT_B,*buffer,rxlen); 

receive(PORT_B, •buffer) ; 
if (fxlen) 

transait (PORTIA, •buffer, rxlen) 
} 


/• receive on port A •/ 

/• if packet received •/ 

/• resend it on 
port B •/ 

/• now receive port B •/ 

/• if packet received •/ 

; * /• resend it on 

port A •/ 


There are two types of functions which enable you to change 
protocol parameters: 

mIh ^set__xxx These functions set the parameter for 

the specified port. For example, the 

mih set t1 sets the value of the T1 

timer forTFe specified port. 

set__xxx These functions set the parameter to an 

Identical value for both ports. For 
example, set__t1 sets the value of the T 1 
timer to the same value for both ports. 
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flush 

Declaration 

Description 

Returns 

See Also 


flush 0 


This function clears the receive buffer of the currently selected 
port. 

The set port function enables you to select a port. (See 
AppendnTB.I for a description of set port.) 


None 


set port(), flush all(), mih flush() 
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flush all 


Declaration 


Description 


Returns 


See Also 


flush all() 


This function clears the reception buffer of both ports. 


None 

fiush(), mlh ^flush() 
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init a 


Declaration 


Range 


Description 


Returns 


See Also 


int init a (interface, sta, encode, bitrt) 
int inferface, sta, encode; 
long bitrt; 


interface 0 DCE 

1 DTE 

2 ISDN 


sta 0 Network 

1 Subscriber 

encode 0 NR2 

1‘ NRZI 

bitrt 50 to 64000 bps 

The bit rate selection is used to optimize some 
functions, so it should be set to the correct value 
even when the Ch^eleon is simulating a DTE or 
when an ISDN interface is being used, if you are 
unsure of the appropriate bit rate, use 50. 


This function initializes Port A according to the passed 

parameters. Port B must then be initialized using the init b 

function. If both Ports A and B are to be initialized using 
identical parameters, use the initpl function. 


0 Operation successfuly completed 
-1 Parameter error 

Also see the common error codes in Appendix B.1 . 


initpl 0, init b() 
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init_b 

Declaration 


Range 


Description 


Returns 


See Aiso 


int init b (interface, sta, encode, bitrt) 
int iriferface, sta, encode; 
long bitrt; 


interface 0 DCE 

1 DTE 

2 ISDN 

sfa 0 Network 

1 Subscriber 


encode 0 NRZ 
1 NRZI 


bitrt 50 to 64000 bps 

The bit rate selection is used to optimize some 
functions, so it should be set to the correct value 
even when the Chameleon is simulating a DTE or 
when an ISDN interface is being used. If you are 
unsure of the appropriate bit rate, use 50. 


This function initializes Port B according to the passed 

parameters. Port A must then be initialized using the Init a 

function. If both Ports A and B are to be initialized using 
identical parameters, use the initpt function. 


0 Operation successfuly completed 
-1 Parameter error 

Also see the common error codes in Appendix B.1 . 


initp1(), init a() 
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initpl 

Declaration 


Range 


Description 


Returns 


See Also 


int initpl (interface, sta, encode, bitrt) 
int interface, sta, encode; 
long bitrt; 


interface 0 DCE 

1 DTE 

2 ISDN 


sta 0 Network 

1 Subscriber 

encode 0 NR2 

1 NR2I 


bitrt 50 to 64000 bps 

The bit rate selection is used to optimize some 
functions, so it should be set to the correct value 
even when the Charheleon is simulating a DTE or 
when an ISDN interface is being used, if you are 
unsure of the appropriate bit rate, use 50. 


This function initializes both Ports A and B according to the 
passed parameters, if the two ports must be initialized with 

different parameters, use init a and init b to set each port 

independently. 


0 Operation successfuly completed 
-1 Parameter error 

Also see the common error codes in Appendix B.1. 


init a(), init b{) 
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mih flush 


Declaration 


Range 


Description 


Returns 


See Also 


mIh flush (port) 

Int port; 


port 0 Port A 
1 Port B 


This function clears the receive buffer of the specified port. 


None 


flush(), flush all() 
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mih receive 


Declaration 


Range 

Description 


Returns 


See Also 


int mIh receive (loc) 

char loc; 


loc A pointer to the user defined buffer. 


This function causes the Chameleon to check for a received 
packet. An internal flag is maintained to indicate which port 
supplied the last packet. This flag gives priority to the other 
port on the next call so that one port does not dominate the 
system during heavy traffic. If the currently preferred port 
does not have a received packet to pass, the port that 
received the last packet is then queried. 

For example, if a packet is received from Port A, the next call 
checks the Port B reception buffer. If Port B does not have a 
packet, it then queries Port A. 

When a packet is detected in the reception buffer: 

• The packet is transferred from the message reception 
buffer to a user defined buffer pointed to by loc. 

• The global variable rxlen is set to the length of the 
received packet. 

• It sets the global variable rec port to indicate from 

which port the packet was received, as follows: 

0 No packet was received 

1 Packet received from Port A 

2 Packet received from Port B 


0 No packet in the reception buffer 

2 FEP not initialized 

128 Packet received 

Also see the common error codes in Appendix B.1. 


receiveO 
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mih set 


Declaration 


Range 


Description 


Returns 


See Also 


Tekelec 


n1 


int mIh set n1 (port.val) 

int porCval; 

port 0 Port A 
1 Port B 

vat N1 value in the range 1 to 512. 

This function sets the N1 value for the specified port. 

The set__n1 function sets both ports to the identical N1 value. 

0 Successful 
-1 Parameter error 

Also see the common error codes in Appendix B.1. 


set n1{) 
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mih set 


Declaration 


Range 


Description 


Returns 


See Aiso 


n2 


int mIh set n2 (port,val) 

int porflival; 


port 0 Port A 
1 Port B 

val N2 value in the range 1 to 512. 

This function sets the N2 value for the specified port. 

The set n2 function sets both ports to the identical N2 value. 


0 Successful 
-1 Parameter error 

Also see the common error codes in Appendix B.1. 
set n2{) 
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mih set 


Declaration 


Range 


Description 


Returns 


See Also 


net 


int mIh set net (port) 

int porf^al; 


port 0 Port A 
1 Port B 

This function sets the specified port to act as a network. 

The set net function configures both ports to act as networks. 


0 Successful 

Also see the common error codes in Appendix B.1. 


set net() 
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mih set 


Declaration 


Range 


Description 


Returns 


See Aiso 


int mIh set ^t1 (port,val) 

int porf;val; 


port 0 Port A 
1 Port B 

val T1 value in the range 1 to 255 seconds. 

This function sets the value of the T1 timer for the specified 
port. 

The set t1 function sets both ports to the identical T 1 value. 


0 Successful 
-1 Parameter error 

Also see the common error codes in Appendix B.1. 


set t1 {) 
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mih set 


Declaration 


Range 


Description 


. Returns 


See Also 


t2 


int mIh set___t2 {port,val) 
int por^val; 


port 0 Port A 
1 Port B 

val T2 value in the range 1 to 255 seconds. 


This function sets the value of the T2 timer for the specified 
port. 

The set__t2 function sets both ports to the identical T2 value. 

0 Successful 
-1 Parameter error 

Also see the common error codes in Appendix B.1. 


set t2() 
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mih slof 


Declaration 


Range 

Description 


Returns 


See Also 


int mIh slof (port) 
int porfP 


port 0 Port A 
1 Port B 


This function disconnects the link on the specified port by 
sending a DISC frame. 

The slof function disconnects the link on both ports. 


See the common error codes in Appendix B.1. 


slofO 
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mih sion 


Declaration 


Range 

Description 


Returns 

See Also 


int mIh slon (port) 
int porff 


port 0 Port A 
1 Port B 


This function attempts to establish a link on the specified port 
by sending a SABM. 

The slon function attempts to establish links on both ports. 


See the common error codes in Appendix B.1. 


slon() 
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mih status 


Declaration 


Range 

Description 

Returns 


See Also 


int mIh status (port) 
int porfT" 


port 0 Port A 
1 Port B 


This function returns the link status of the specified port. 


0 Disconnected 

1 Link connection requested 

2 Frame reject state 

3 Link disconnection requested 

4 Information transfer state 

5 Local station busy 

6 Remote station busy 

7 Local and remote stations busy 


Also see the common error codes in Appendix 6.1 . 


statusO 
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mih set 


Declaration 


Range 

Description 


Returns 


See Also 


sub 

int mIh set sub (port) 

int porff" 


port 0 Port A 
1 Port B 

This function sets the specified port to act as a subscriber. 
The set___sub function sets both ports to act as subscribers. 

0 Successful 

Also see the common error codes in Appendix B.1. 

set sub() 
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mih set 


Declaration 

Range 


Description 


Returns 


See Also 


window 


int mIh set window (port,val) 

int port,van" 


port 0 Port A 
1 Ports 

val Window size in the range 1 to 7 frames 


This function sets the window size (maximum number of 
outstanding unacknowledged frames) for the specified port. 

The set window function sets the window size of both ports 
to the identical value. 


0 Successful 
-1 Parameter error 

Also see the common error codes in Appendix B.1. 


set windowO 
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mih trans 


Declaration 


Range 


Description 


Returns 


See Also 


int mIh trans (xloc,xlen) 
char *x1oc; 
int xlen; 


x/oc Pointer to the user defined packet to be transmitted 

xlen Length of the packet to be transmitted 


This function transmits a data packet on Port A or B as 
determined by the distribution pattern set by a call to the 
sef^pat or the set__ratio function. 

mih transO should be used to transmit information packets 

only. Other packet types should be sent using the transmit() 
function, which has a passed argument selecting the port. The 
only time it is safe to send non-info packets using mih trans{) 
Is when the distribution pattern is specified as recRjndant 
(set ratio{-1 ) is selected). 


0 Successful 

Also see the common error codes in Appendix B.1. 


transmitO, set pat{), set ratio() 
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receive 


Declaration 


Range 


Description 


Returns 


See Also 


int receive (portjoc) 
char loc; 
int port; 


port 0 Receive from Port A 
1 Receive from Port B 

loc A pointer to the user defined destination buffer. 


This function checks the reception buffer of the specified port 
for a received packet, if a packet has been received: 

• The packet is transferred from the message reception 
buffer to a user defined buffer 

• The global variable rxlen Is set to the length of the 
received packet 

The mih ^receive function is another receive function. It 

alternates between Ports A and B when called. Calling 
receiveO does not affect the alternating pattern of 
mih receive. 


0 No packet in the reception buffer 

2 PEP not initialized 

128 Packet received 

Also see the common error codes In Appendix B.1. 


mih receiveO 
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set n1 

Declaration 

Range 

Description 

Returns 

See Also 


int set n1 (val) 

int val; 


val N1 value in the range 1 to 512 


This function sets the N1 value for both ports. 

The mih set n1 function sets the N1 value of a specified 

port. 


0 Successful 
-1 Parameter error 

Also see the common error codes in Appendix B.1. 


mIh set n1{) 
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set n2 


Declaration 

int set n2 (val) 
int val; 

Range 

va! N2 value in the range 1 to 51 2 

Description 

This function sets the N2 value for both ports. 


The mih set n2 function sets the N2 value of 
port. 

Returns 

0 Successful 
-1 Parameter error 


Also see the common error codes in Appendix B.1 

See Also 

mIh ^set ^n2() 


Specified 


Tekelec 


B. 13-29 


Version 2.5 





Chameleon 32 C Manual 


Appendix B.13: Multi-Link HDLC Library 


set net 


Declaration 

Description 


Returns 


See Aiso 


int set net 

This function configures both ports to act as networks. 

The mih set net function configures the specified port to act 

as a network. 

0 Successful 

Also see the common error codes in Appendix B.1. 

mIh set net() 
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set pat 

Declaration 

Range 


Description 


Returns 

See Also 


int set pat (pat ptr) 

char 'pat ptr; 


pat_ptr A pointer to a user defined table which specifies the 

distribution pattern the for mih ^trans() transmit 

function 


This function enables you to specify a user defined distribution 
pattern for transmitting packets using the mIh ^trans function. 

The distribution pattern is defined in a table which contains the 
following values: 

0 End of table 

1 Send on Port A 

2 Send on Port B 

The table may be of any length, but it must be a character 
(byte) oriented table which contains at least one port selection 
code and terminates with an end of table code (0). 

With each packet transmitted, mih ^trans increments a pointer 

into the pattern table. When the pointer lands on a zero entiy 
in the table, or a new pattern selection is made, the pointer is 
reset. 

The set ratio function provides an alternate means of defining 
a distribufion pattern. 


See the common error codes in Appendix B.1. 


mih transO, set ratio(), transmit() 


Tekelec 


B. 13-31 


Version 2.5 





Chameleon 32 C Manual 


Appendix B.13: Multi-Link HDLC Library 


set^ratio 

Declaration 


Range 


Description 


Returns 


See Also 


int set ratio (pet a) 

int pet a; 


pcf__a The pereentage of paekets to be transmitted over 
Port A. Valid values are 0 to 100 in inerements of 
1 0, and -1 . 


-1 All paekets are transmitted over both Ports A 
and B. This is also referred to as redundant 
mode. 

0 0% of the paekets are transmitted over Port A. 

(All packets are transmitted over Port B.) 

10 10% of the packets are transmitted over Port 

A. 90% are transmitted over Port B. 

20 20% on Port A, 80% on Port B. 

• * 

90 90% on Port A, 10% on Port B. 

100 All packets sent on Port A 


This function selects a distribution pattern for transmitting 
packets using the mlh trans function. It specifies the 
percentage of packets to “Be transmitted over Port A. 

The set pat function provides an alternate means of defining 
a distribufion pattern. 


0 Successful 
-1 Parameter error 

Also see the common error codes in Appendix B.1. 


mlh transO, set pat() 
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set sub 

Declaration 

Description 

Returns 

See Aiso 


int set sub () 

This function configures both ports to act as subscribers. 

The mih set sub function configures the specified port to 

act as a subscriber. 

0 Successful 

Aiso see the common error codes in Appendix B.1. 

mIh set sub() 
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set t1 


Declaration 


Range 

Description 


Returns 


See Also 


int set__t1 (val) 
int val; 


val T 1 timeout value in the range 1 to 255 seconds. 


This function sets the T1 timer to an identical value for both 
ports. 

The mih set ^t1 function sets the value of the T 1 timer of the 

specifie<rport. 


0 Successful 
-1 Parameter error 

Also see the common error codes in Appendix B.1 . 


mIh set t1 0 
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set ^12 

Declaration 

Range 

Description 

Returns 

See Also 


int set t2 (val) 

int val; 


va/ T2 timeout value in the range 1 to 255 seconds. 


This function sets the T2 timer to an identical value for both 
ports. 

The mih set__t2 function sets the value of the T2 timer of the 
specifleiTport. 


0 Successful 
-1 Parameter error 

Also see the common error codes in Appendix B.1. 


mIh set t2() 
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set window 


Declaration 


Range 

Description 


Returns 


See Also 


int set ^window (val) 

int val; 


va/ Window size in the range 1 to 7 frames. 


This function sets the window size (maximum number of 
outstanding unacknowledged frames) to an identical value for 
both ports. 

The mih set ^window function sets the window value of the 

specifiecTport. 


0 Successful 
-1 Parameter error 

Also see the common error codes in Appendix B.1. 


mih set windowO 
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slof 


Declaration 


Description 


Returns 


See Aiso 


int slof 0 

This function disconnects the link on both ports by sending a 
DISC frame. 

The mih slof function disconnects the link on a specified port. 


See the common error codes in Appendix B.1. 


mlh slof() 
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sion 

Declaration 

Description 

Returns 

See Also 


int slon () 


This function attempts to establish a link on both ports by 
sending a SABM. 

The mih slon function attempts to establish a link on a 
specifiecTport. 


See the common error codes in Appendix B.1. 


mIh slon() 
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status 


Declaration 


Description 


Returns 


See Also 


int status () 


This function returns the link status of the currently selected 
port. 

Use the set port function to select a port (Appendix B.1 ). 


0 Disconnected 

1 Link connection requested 

2 Frame reject state 

3 Link disconnection requested 

4 Information transfer state 

5 Local station busy 

6 Remote station busy 

7 Local and remote stations busy 


Also see the common error codes in Appendix B.1. 


set port(), mlh status() 
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transmit 


Declaration 


Range 


Description 


Returns 


See Also 


int transmit (port,xloc,xlen) 
char port,*xloc; 
int xlen; 

port 0 Port A 
1 Port B 

x/oc Pointer to the user defined packet to be transmitted 

xlen Length of the packet to be transmitted 


This function transmits a packet over the specified port. 

The mih ^trans function is an alternate function which 

transmits packets over Ports A and B as determined by a 
specified pattern. The transmit function does not affect the 
mIh trans pattern. 


0 Successful 

Also see the common error codes in Appendix B.1. 


mih transO 
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Sample 
Program 1 


This program starts port to port simulation on a Dual Port 
Chameleon. To use the program, connect Port A to Port B. 
The program initializes the ports and runs continuous 
transmit/receive on alternate ports until stopped by the user or 
the link goes down. It counts and displays the content and 
number of frames received on each port. 

finclude <stdio.h> 
finclude <chaB.h> 
finclude <ctype.!i> 
iindude <fcnt1.h> 
finclude <init.h> 

char tasg[48],nisg[48]; 

•ain() 

{ 

char ans«er,1ns1t.^tadr,^radr; 
extern char ^aallocO; 
extern int rxlen; 

Int result, teapi; 
long Int count, countb; 

printf(”C prograa started. \n”); 

tadrs&tasgCO]; 

radr«8trasg[0]: 

s_start(0); 

s_start(l); 

/••••• make and display transait aessage 

for( ins1t=0; insi t<=16; insit++) 
tasgCinsit] = insit; 

pr1ntf( "aessage = •); 
f or( insit=0; insit<=16; insit-H-) 
printf(" XOx *,tasg[ insit]); 
printfCXn"); 

fraae level setup •••••/ 

resul t=set_n 1 ( 0x50 ) ; 
printf("set nl result- Xd\n*, result); 
resul t=se t_t 1 ( 10 ) ; 
resu 1 t=se t_n2 ( 4 ) ; 
result=set_aindoa(3) ; 

alh_set_net{0); /• Port A is network •/ 
alh_set_sub(l); /♦ Port B is subscriber •/ 
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printf(*Type Q to exitVn*); 

/••♦•start link fro« port B, wait for port A state 
■lli_s1on(l); 

«hile(a1h_status(0)<4) ; 

/mmmmm receive untill port A link state is less than 4 

or user types *0* key •••••/ 

count-countb~0 ; 

for(;;){ 

if (status()<4) break; 

answer = getch(_stdvt); 
if (toupper(answer)->*Q* ) 
break; 

resul t~trans( 1 *0x80, tadr , 10) ; 
resul t»recei ve( 0 , radr ) ; 
if(rx1en>0) 

{ 

printf("port A received wessage * ■); 
f or( insit»0; insi t<rx1en; insit4-i-) 

printf(* XOx *»rwsg[insit]); 
printf(*\n\n*); 
count'*-**; 

} 

resul t=trans( 0 , 0x80 , tadr , 10 ) ; 
resul t»receive( 1 , radr ) ; 
if(rx1en>0) 

{ 

printf{*port B received wessage ~ *); 
for(insit-0;insit<rxlen;insit4’**) 
printf(* XOx * ,raisg[ insit]); 

} 

i f ( w1 h_s tatus ( 1 ) ) 

resul t-trans ( 1 « 0x80 , tad r , 15 ) ; 
countb-t-*-; 

printfC\033[Xd;Xdf.ll.l5); /-• xyplot V 
printf("\033[31wThat*s Xld on A, Xld on b.\n",count,countb); 
} 

f or { count-0 ; coun t<0xf f f ; coun t++ ) ; 

Still connected* disconnect it, then exit •••••/ 
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1f(status()>0) 

{ 

result=s1of (); 

■hile(status( )>0) ; 

} 

} 

s_start(port) 

Int port; 

{ 

int rets,ret2,vaiter; 
long int rate; 

rate=^64000; 

printf( "Trying to start PI"); 
if(!port) 

rets- init_a(0, 0,0, rate); 
else 

rets- init_b(l, 1,0, rate); 

printf(" result = X0d\n",rets); 
f or( ret2-0 ; ret2<0xf f f f ; ret2++) 

for( rets=0; rets<0xffff ; rets++) 
f or(vaiter=0 ;«ai teKOxf f f f ;oai ter++) ; 


} 
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Sample 
Program 2 


Tekelec 


This program starts port to port simulation. It runs continuous 

transmit/receive on both ports using mih ^trans and set ratio 

until stopped by the user or the link goes down. It counts and 
displays the content, number of frames, and ratio of frames 
received on each port. Note that the displayed ratio is only 
aproximate, as it is calculated using integers. 

#include <std1o.h> 
finclude <cha 0 .h> 

#iiic1ude <ctype.h> 

#1nclude <fcntl.h> 

#ific1ude 

finclude <v1deo.h> 
finclude <nth.h> 

ctier tasg(;48],rasg[48]; 

•ainO 

{ 

char insit, answer, ^tadr,*radr; 

extern char ♦■all oc(), reexport, pat_tbl .•pat_loc,tpat jitr; 

extern int rxlen; 

int ab_ratio,resu1t,teapi; 

long int count, countb; 

char ^place; 

tadrsfttasgCO]; 

radrs&ra$g[0]; 

s_start(0); 

s_start(l); 

display transmit aessage 
f or ( i nsi t =0 ; i ns i t<= 16 ; i ns i t-w- ) 

tasgCinsit] - insit; 

printf(*aessage = •); 
f or( insi t*0; insit<=16; insit-*-*-) 
printf(“ XOx *,tasg[insit]) ; 
printf{*\n*); 

do fraae level setup 

resul t~set_n 1( 0x50 ) ; 
printf(*set nl result- Xd *, result); 
result*set_tl( 10); 

printf(*set tl result* Xd ", result); 
resul t*set_n2 ( 4 ) ; 

printf(*set nZ result* Xd *, result); 
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resul t=set_«i ndcm( 3 ) ; 
pr1ntf(”set vindow resul t= Xd\n”, result); 

■lh_set_net(0); 

pr1ntf("set net port A resul t= Id *, result); 

■lh_set_sub(l); 

printf(”set sub port B resul t= Xd\n”, result); 
ab_ratio=“l; 
set_ratio( ab_ratio) ; 

printf(*set ratio result^: Xd\n*, result); 

printf( "Press space bar to change port ratio, Q to exit\n*); 

/•••♦start link fro« port B, wait for both ports state 4 ••••/ 

■lh_slon(l); 

«h i 1 e(al h_status( 0 )<4 ) ; 

«h i 1 e( ■! h_status( 1 )<4 ) ; 

/••••• send and receive untill port A link state is less than 4 
count-countb=0; 
for(;;){ 

if(status()<4) break; 
resul t~«lh_trans(tadr, 12) ; 
resul t^l h_receive( radr ) ; 
if(rxlen>0) 

{ 

if ( reexport ==1) 

{ 

printf("port A received Message = "); 
for( insit=0; insit<rxlen; insit-w*) 
printf(* XOx *,rasg[insit]); 
printf ("XoNn"); 
i f ( ( count>0 )&&( coun tb>0 ) ) 

{ 

printf ("Ratio of fraaes on ports A:B - "); 

count>countb? printf("Xld:l \n",count/countb):printf ("l:Xld 

\n" ,countb/count) ; 

} 


COUnt*M-; 

} 

if ( reexport ==2) 

{ 

printf("\nport B received Message == "); 
for(insit=0;insit<rxlen;insit-M-) 
printf(" XOx ",rMsg[insit]); 
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printf ( •\n"); 
countb-M-; 

} 


} 

answer = getch(_stdvt); 

if (toupper(answer)--'Q' ) 
break; 


if (answer—* *) 

{ 

if(ab_ratio— -1) 
ab_ratio*0; 

else 

ab_ratio+=10; 

if(ab_ratio>100) 

ab_ratio»-l; 

count=countb-0; 

flush^allO; 

printf{*\nset ratio result Xd \n* ,set_ratio{ab_ratio)); 

printf ("XnRatio selection * Xd\n*,ab_ratio); 

} 

printf ( ■\033CXd;Xdf ’ ,11,13); 
printfC\033C31aThat's Xld on A, tid on B. 

Vn* , count , countb ) ; 

} 

/mmmmm still connected, disconnect it, then exit 

if($tatus()>0) 

{ 

result*slof{); 
while(status( )>0) ; 

} 

> 

s_start(port) 
int port; 

{ 

int rets, ret2, waiter; 
long int rate; 

rate~64000; 

printf (•Trying to start PI*); 
if(!port) 
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rets= init_a(0, 0,0, rate); 
else 

rets= init_b( 1,1,0, rate); 

printf{" result = 10d\n*,rets); 
f or( ret2=0 ; ret2<0xf f f f ; ret2'*-«') 

f or( rets=0; rets<0xf f f f ; rets-M*) 
for(waiter=0;wa1teK0xffff ;waiten-f); 

} 
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Sample 
Program 3 


this program demonstrates the use of many of the Multi-Link 
HDLC library functions. To run the program as a Chameleon 
self-test, connect Port A to Port B on a Dual Port Chameleon. 

#iiic1u(le <stdio.h> 

#inc1ude <ciiaa.h> 
finclude <ctype.h> 
finclude <fcfitl.h> 
finclude <in1t.h> 
finclude <video.h> 
find ude <«ath . h> 

char tasgC48],rBsg[48], answer; 

■a1n() 

{ 

Char insit,^tadr,^radr; 
extern int rxlen; 
int result; 

long int count, countb; 

tadrs&tasg[0] ; 
radrs&r«isg[0]; 
s_start(0); 
s_startCl): 


wake and display transait aessage 

for(insit*0;insit<»16;insit*i-<') 

tasgCinsit] ~ insit; 

printf(”aessage = ■); 
f or( i ns i t=0 ; i ns i t< * 16 ; i ns i t++ ) 
printf{* tOx *,tasg[ insit]); 
printf(*\n*); 

do fraae level setup 

resul t*set_n 1 ( 0x50 ) ; 
printf(*set nl result- Xd ", result); 
resul t»set_tl( 10) ; 

printf(*set tl result* Xd result); 
resul t*set_n2 ( 4 ) ; 

printf(*set nZ result* Xd ", result); 

resul t*set_wi ndow( 3 ) ; 
pr1ntf(*set window result* Xd\n*, result); 

resul t=al h_set_net( 0 ) ; 

printf{*set net port A result* Xd ", result); 
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resul t=«l h_set_sub( 1 ) ; 

printfCset sub port B result= Xd\n*, result); 


run test until finished or user quits •••••/ 
while (1) 

{ 

re_paint(); 

if (toupper(ans«er)~-'Q*) 
break; 

printfC\033[40*\033[Xd;Xdf.ll,13);/^ xyplot •/ 
printf(*\033[35Mlh_slon/Blh_slof test. Next test: flush_all*); 


printfC\033[Xd;Xdf.l3,13);/^ xyplot •/ 
printf(”\033[35aResult of alh^slon/Blh^slof test: \n”); 

«hile(l) 

{ 

■1ii_s1on(0); 

«li11e(a1h_status(0)=^l); 
if (■1h_status(0)°’»0) 

{ 

no_good(); 

break; 

} 

■Ih.slof(O); 
settiaer(2,2); 
while (tiaer(2)); 
if (■lh_status(0)l=0) 

{ 

no ^ood(); 
break; 

} 

■lh_slon(l); 

whi le(al h_status( 1 )==1 ) ; 
if (■lh_status(l)=*0) 

{ 

nojgoodO; 

break; 

} 

■lh_slof(l); 
settiaer(2,2); 
while (tiaer(2)); 
if (■lh_status(l)!=0) 

{ 

no _ 900 d(); 
break; 

} 

test_passed( } ; 
break; 

} 
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re_paint(); 

priiitfC\033[Xd;Xdf.ll,13);/^ xyplot V 

printf(”\033[40a\033[35flflusli_al1 test Next test: ■1h_flush(port)*) ; 

printfC\033[Xd;Xdf.l3.13);/* xyplot V 
printf(*\033[35aResu1t of flush^all test: \n"); 

set_ratio(-‘l); /*so 1 trans call will send on both ports*/ 
■1h_slon(l); 

«hi1e(«lh_status( 1)=»1) ; 

resul t-alh_trans( tadr, 12) ; 
flush^allO; 

resul t=«l h_recei ve( radr ) ; 

1f(rxlen>0) /*s/b no fraae on either port*/ 
no_good(): 

else 

test_passed( ) ; 
re_paint(); 

printfC\033[Xd;Xdf,11.13);/* xyplot */ 
printf(”\033[40B\033[35«ilh_flush(port) Last test”); 

printfC\033[Id;Xdf .13.13);/* xyplot */ 
pr1ntf(*\033[3S«Result of alh^flushCport) test: \n”); 


«h11e(l) 

{ 

resul t^lh_trans(tadr. 12);/* send f rases. both ports*/ 
■lh_flush(0); /*flush port A*/ 
resul t- recei ve ( 0 , rad r ) ; 

if(rxlen) /* fail if port A not flushed */ 

{ 

no_ 90 od( ) ; 

printf(”port A failed to flush”); 
break; 

> 

resul t-receive( 1 , radr) ; 

if(lrxlen) /* fail if port B is flushed */ 

{ 

no_good(); 

printf(”port B flushed with A”); 
break; 

} 

resul t>al h_trans{ tadr . 12 ) ; 
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■lh_flush(l); /•flush port BV 
resul t=recei ve( 1 , radr) ; 

if(rxlefi) /• fall if port B not flushed •/ 

{ 

no_good(); 

printf(*port B failed to flush*); 
break; 

} 


resul t=recei ve( 0 , radr) ; 

if(!rxlen) /• fail if port A is flushed •/ 

{ 

no_good( ) ; 

printf(*port A flushed with port B*); 
break; 

} 

test_passed( ) ; 
break; 

} 

printf(*\033[Xd;Xdf*,9.13);/^ xyplot V 

printf(*\033[40aV033C34«Press Q to exit, space to restart \n”); 
ans»er~0; 

while ((answerl-* * }&&(toupper(ans«er)l-*Q* )) 
answer > getch(_stdvt); 
if (toupper(answer)s>*Q') 
break; 

printf(*\033[0J*); 

> 

/••••• if link still connected, disconnect it, then exit •••••/ 

if(status()>0) 

{ 

result>slof(); 
while(status( )>0) ; 

} 

} 

re_pa1nt() 

{ 

printf{*\033[Xd;Xdf*,9,13);/* xyplot V 

printf(*\033{]40w\033C34aPress space bar to run test \n*); 

answer-0; 

while (answer!^* •) 

{ 

ansmr = getch(_stdvt); 
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} 

priiitfC\033[0J*); 

} 

no_ 90 od( ) 

{ 

printfCV033[Xd;Xclf,14.13);/^ xyplot •/ 
printf ( •\033[30«\033[41«FAILED • ) ; 

} 

test_passed( ) 

{ 

printfC\033[Xd;Xdf.l4.13);/* xyplot V 
printfC\033[30«\033[42«PASSEO •); 

} 

s_s tart (port) 
lilt port: 

{ 

lot rets,ret2,«aiter; 
long Int rate; 

rates64000; 

printf( •Trying to start PI*); 
if(lport) 

retss 1n1t_a(0»0,0»rate); 
else 

retss 1n1t_b( 1,1,0, rate); 

printf(" result * X0d\n*,rets); 
f or{ ret2-0 ; ret2<0xf f f f ; ret2+^) 

f or{ rets-0 ; rets<0xf f f f ; rets-*^) 
for(«ai tersQ ;ea1 teKOxf f f f ;»ai ter+4-) ; 

} 
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B.14 U-INTERFACE LIBRARY 


Introduction The U-interface library function enables you to use the Chameleon 

32 U-interface hardware (the U-board) in the C environment. The 
library is called libu.a, and is in the \iib directory. The function call 
described below interfaces the U-interface library from C 
programs. 

Two sample programs are given beginning on page B.14-14. 


SetU 


Declaration int SetU (cmdbiock, resbiock); 

char cmdblock[ ]; 
char resbiock[ ]; 

int SetU is the function call for .accessing the U-board from the C 
Shell. 


Description This function has two parameters blocks that are character (char) 

arrays. The size depends upon the requested function. 


The cmdbiock (command block) parameter contains the input 
parameters needed. The first item, cmdbiock [0], is a character 
specifying the requested function. The remaining items are 
function-specific parameters. 


The resbiock (result block) parameter contains the results of the 
operation requested in the cmdbiock. The first item, resblock[0], is 
a character indicating whether or not the command was completed 
successfully. The remaining items are function-specific results. 


The commands listed on the next page are available as the first item 
in cmdbiock. The commands are different for U-boards 0 and 1 to 
distinguish between the two boards installed in your Chameleon. 
However, if you have only one U-board in your Chameleon, you 
must use the commands that correspond to that board. 
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Board 0 

Board 1 

Command 

0 

100 

Initialize Interface 

1 

101 

Configure 

2 

102 

Set Transceiver State 

3 

103 

Get Transceiver State 

4 

104 

Set Transceiver Activation 

5 

105 

Get Transceiver Connection 

6 

106 

Set Transceiver Cfio. a 

7 

107 

Get Transceiver Errors 

8 

108 

Get HW Version 

9 

109 

Get Link Status 

11 

111 

Transceiver Transmit 

12 

112 

Transceiver Receive 

13 

113 

EOC Processing 

14 

114 

EOC Mode Control 

15 

115 

M4 Mode Control 

16 

116 

M5/6 Mode Control 

30 

130. 

Shutdown Interface 


The commands are described on the following pages. 


resbiock[0] 

Error Codes The error codes for resblock[0] are the same for all LMnterface 

Library commands. 


Code 

Meaning 

00 

Successful 

01 

invalid Command 

02 

Invalid Command Parameters 

03 

Requested board is not responding 

04 

U-board physical error 

05 

U-board interface is not initialized 

10 

Requested board is not installed 
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cmdblock[0] = 0 
cmdbiock[Oj =100 
Initialize 

This command is used to initiaiize the C Libra^ interface. This 
includes actions such as allocating memory, getting unit identifiers, 
enabling reception, etc. This command should be the first 
command issued when using the U Interface. 


The response parameter for this function is resblock[0]. See Error 
Codes. 


cmdblock[0] = 1 
cmdblock[0] = 101 
Configure 


This command is used to set up the U board for monitoring or 
simulating the M channel and the 2B-I-D channels. It also specifies 
the routing of the 2B-»‘D-channel data. 


Configuration for the M channel: 

cmdbiock[1] Mode of operation 

00000000 Customer Equipment (NT) Simulation. 
00000001 Network Equipment (LT) Simulation. 
00000010 Monitoring 


Configuration for the 2B+D channels: 


cmdblock[2] Mode of operation 

00000000 Customer Equipment (NT) Simulation. 
00000001 Network Equipment (LT) Simulation. 
00000010 Monitoring 

cmdblock[3] Codec encode 

00000000 p.-Law 
00000001 A-Uw 

cmdblock[4] ClocWng (Valid only in LT simulation) 

00000000 External 
00000001 Internal 
00000010 NT-Recovered 


cmdblock{5] 


B1 -Channel Routing 
00000000 None 
00000001 Port A 
00000010 Ports 
00000011 Idle pattern 
00000100 X1 
00000101 X2 
00000110 Codec Handset 
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000001 1 1 Codec 600-0hm . 


cmdblock[6] B2-Channe! Routing 
00000000 None 
00000001 Port A 
00000010 Ports 
00000011 Idle pattern 
00000100 XI 
00000101 X2 
000001 1 0 Codec Handset 

00000111 Codec 600-0hm. 

cmdblock[7] D-Channel Routing 
00000000 None 
00000001 Port A 
00000010 Ports 
000000 11 Idle pattern 
00000100 XI 
00000101 X2 


cmdblock[8] Si-Channel Idle Pattern 
cmdbIock[9] S2-Channel Idle Pattern 
cmdblock[10]D-Channel Idle Pattern 


The response parameter for this function is resblock[0]. See Error 
Codes. 
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cmdblock[0] = 2 
cmdblock[0] = 102 
Set Transceiver State 

This command is used to set up the state of the specified 
transceiver. 

cmdblockfl] Transceiver specifier 

0 NT Xcvr 

1 LT Xcvr 

cmdblock[2] Transceiver state 

1 Reset 

2 Power down 

3 Absolute 

4 Normal 


The response parameter for this function is resblocl^O]. See Error 
Codes. 


cmdblock[0] = 3 
cmdblock[0] = 103 
Get Transceiver State 

This command is used to set up the state of the specified 
transceiver. 


cmdblock[1] Transceiver specifier 

0 NT Xcvr 

1 LTXcvr 


The response parameters for this function are: 

resblock[0] See Error Codes 
resblock[1 ] T ransceiver state 

0 Reset 

1 Power down 

2 Absolute 

3 Normal 
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ctndbiock[0] = 4 
cmdbiock[Oj = 104 
Set Transceiver Activation 

This command is used to start transceiver activation or 
deactivation. 


cmdblockfl] Transceiver specifier 

0 NTXcvr 

1 LTXcvr 

cmdblock[2] Transceiver activation 

1 Start activation 

2 Start deactivation 


The response parameter for this function is resblock[0]. See Error 
Codes. 


cmdblock[0] = 5 

cnidblock[0] = 105 

Get Transceiver Connection 

This command is used to get the connection status of the specified 
transceiver. 

cmdblockfl] Transceiver specifier 

0 NTXcvr 

1 LT Xcvr 


The response parameters for this function are: 

resblockfO] See Error Codes 
resbiockfl ] T ransceiver connection 

0 None 

1 Port A 

2 Ports 

3 Ports A and B 
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cmdblock[0] = 6 
cmdbiock[Oj = 106 
Set Transceiver Errors 

This command is used to reset the error counters of the specified 
transceiver. 

cmdblock{1] Transceiver specifier 

0 NTXcvr 

1 LTXcvr 


The response parameter for this function is re$btock[0]. See Error 
Codes. 


cmdblock[0] = 7 
cmdblock[0] = 107 
Get Transceiver Errors 

This command is used to retrieve the 32-bit error counters of the 
specified transceiver. 

cmdblock[1] Transceiver specifier 

0 NT Xcvr 

1 LT Xcvr 


The response parameters for this function are: 
resbiock[0] See Error Codes 

resblock[1-4] 32-bit FEBE count. MSBs followed by LSBs. 
resblock[5-8] 32-4)lt NEBE count. MSBs followed by LSBs. 
resblock[9-12] 32-bit NoSyn count. MSBs followed by LSBs. 
resblock[13-16] 32-bit NoAct count. MSBs followed by LSBs. 
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cmdblock[0] = 8 
cmdblock[0] = 108 
Get HW Version 

This command is used to get the version numbers of the transceiver 
pair. 


The response parameters for this function are: 

resblock[0] See Error Codes 
resblock[1] NT transceiver version number. 
resblock{2] LT transceiver version number. 


cmdblock[0] = 9 
cmdbiock[0i = 109 
Get Link Status 

This command is used to get the link status of the transceiver pair. 


The response parameters for this function are: 

resblock[0] See Error Codes 

resblock{1 ] NT Link Status 
bitO link up 

biti superframe sync recognized 
bit2 transceiver activation in progress 
bit3 error indicator 

resblock[2] LT Link Status 
bitO link up 

biti superframe sync recognized 
bit2 transceiver activation in progress 
bits error indicator 
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There is no function cmdblock [0] = 10, 110 


cmdblock[0] = 11 
cmdblock[0] = 111 
Transceiver Transmit 

This command Is used to transmit data on the M channel. Four 
types of information are allowed: EOC, M4, M5 and M6. 

cmdblock[1] Transceiver specifier 

0 NTXcvr 

1 LT Xcvr 

cmdblock[2] Channel specifier 

1 EOC 

2 M4 

3 M5/M6 


EOC Message 

cmdblock[3] EOC address, EOC DM bit. 
cmdblock[4] EOC Information 


M4 Message 

cmdblock[5] M4 Information 


M5/6 Messages 
cmdblock[6] M5/6 Information 


The response parameter for this function is resblockfOJ. See Error 
Codes. 
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cmdbiock[0] = 12 
cmdblockfO] = 112 
Transceiver Receive 


This command is used to receive the M-Channel information for a 
superframe, including two EOC messages and one M4 and M5/M6 
message each. Table B.6.2-1 illustrates tine coding/decoding 
format of the M-Channel superframe and how this corresponds to 
response parameters of this function. 

cmdblockfl] Transceiver specifier 

0 NT Xcvr 

1 LT Xcvr 


The response parameters for this function are: 


resbiock[0] 

resblock[1] 

resblock[2] 

resblock[3] 

resblock[4] 

resblock[5} 

resblock[6] 

resblock[7] 


See Error Codes 

Message Length 
0 - No data available 
1-6 data bytes follow 

EOC address, EOC DM bit (byte 0 in the table). 
EOC Information (byte 1 in the table). 

EOC address, EOC DM bit (byte 2 in the table). 
EOC Information (byte 3 in the table). 

M4 information (byte 4 in the table). 

M5/6 information (byte 5 in the table). 


BYTE# \ BIT# 

7 

6 

5 

4 

3 

2 

1 

0 

0 (resbiock{2]) 

X* 

X 

X 

X 

a3 

a2 

a1 

dm 

1 (resblock[3]) 

is 

i7 

16 

iS 

i4 

13 

i2 

i1 

2 (resblock[4]) 

X 

X 

X 

X 

a3 

a2 

a1 

dm 

3 (resbiock[5]) 

iS 

i7 

16 

i5 

14 

i3 

12 

i1 

4 {LT->NT) [6] 

ACT 

OEA 

RSV 

RSV 

RSV 

RSV 

UOA 

AIB 

4 (NT->LT) [6] 

ACT 

PS1 

PS2 

NTM 

CSO 

RSV 

SAI 

RSV 

5 {resblock{7]) 

M50 

M60 

M51 

FEBE 

X 

X 

X 

X 


Notes: * s spare bit 

RSV a reserved bit 


Table B.6.2-1: M-Channei Superframe Byte/Bit Format. 
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cmcibiock[0] = 13 
cmdblock[0] = 113 
EOC Processing 


This command is used to configure the U board for automatic EOc 
processing. 

cmdblock[1] Transceiver specifier 

0 NT Xcvr 

1 LT Xcvr 


cmdblock[2] Automatic Processing Mode 

0 No action 

1 Operate 2B-i-D Loopback 

2 Operate B1 Loopback 

3 Operate B2 Loopback 

4 Send Corrupted CRC 

5 Return to Normal 


The response parameter for this function is resblock[0]. See Error 
Codes. 


cmdbiock[0] = 14 
cmdblock[0] = 114 
EOC Mode Control 


This command is used to configure the U board for EOC reception. 

cmdblock[1] Transceiver specifier 

0 NT Xcvr 

1 LT Xcvr 


cmdblock[2] EOC Reception Mode 

0 No action 

1 Handle every EOC 

2 Handle EOC passing trinai checks 

3 Handle EOC passing trinai checks with 

automatic EOC processing 


The response parameter for this function is resblock[0]. See Error 
Codes. 
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cmdblock[0] = 15 
cmdbiock[Oj = 115 
M4 Mode Control 


This command is used to configure the U board for M4 reception. 

cmdblockTIl Transceiver specifier 

0 NTXcvr 

1 LT Xcvr 


cmdblock[2] M4 Reception Mode 

0 No action 

1 Handle Dual-Consecutive M4 with Verified 
act/dea. 

2 Handle Dual-Consecutive M4 

3 Handle Delta M4 

4 Handle every M4 


The response parameter for this function is resblock[0]. See Error 
Codes. 


cmdblock[0] = 16 
cnidblock[0] = 116 
M5/6 Mode Control 


This command is used to configure the U board for M5/6 reception. 


cmdblockfl] Transceiver specifier 

0 NTXcvr 

1 LT Xcvr 


cmdbiock[2] M5/6 Reception Mode 

0 No action 

1 Handle Dual-Consecutive M5/6 

3 Handle Delta M5/6 

4 Handle every M5/6 


The response parameter for this function is resblock[0]. See Error 
Codes. 
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cmdbiock[0] = 30 
cmdblock[0] = 130 
Shutdown 


This command is used to shut the C-Library interface down. This 
includes freeing memory, disabling reception capability, etc. When 
done with the U interface, this command should be the last one 
issued. 


The response parameter for this function is resblock[0]. See Error 
Codes. 
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Sample Programs There are two sample U-Interface programs on the C Sample 

Program Disk: 

• testit.c 

• testntc 


TESTLT.C This program verifies activation of the LT U transceiver and 

reception of EOC messages: i.e., that there is data flowing over the 
M channel. 


# include 

<stdio,h> 


# include 

<mtosxix.h> 


♦define 

NT 

0 

♦define 

LT 

1 

♦define 

LINKUP 

1 

♦define 

ERROR 

8 

♦define 

ERR_NOSTAT 

6 

xinsigned 

char Command [20] , Response [20] 

long 

. febe,nebe; 


/* 




* init^U 

* Initializes and configs U-Board for NT simulation 

* 

*/ 

init_U() 

{ 

Command [0] =« 0; /* Initialize U Library */ 

SetU (Command, Response) ; 
if (Response [ 0 ] ) 

print f (''ERROR: Init - %x\n'', Response [0] ) ; 


Command [ 0 ] ~ 1 ; 

Command [ 1 ] = 0 ; 

Command [2] =0; 

Command [3] = 0; 

Command [ 4 ] =* 1 ; 

Command [5] « 0; 

Command [6] « 0; 

Command [ 7 ] « 0 ; 

Command [ 8 ] =* 0 ; 

Command [9] =* 0; 
Command[10] =* 0; 

SetU (Command, Response) ; 
if (Response [0] ) 

print f ("ERROR: 


/* Config command */ 

/* NT simulation */ 

/* NT simulation */ 

/* U-law */ 

/* Internal Clocking */ 
/* No B1 routing */ 

/* No B2 routing 
/* No D routing */ 

/* Idle patterns */ 


« %x\n" , Response [ 0 ] ) ; 


} 
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/* 

* reset_U 

* Shuts down U-Board 




reset_U() 

{ 

Command [0] = 30; /* shut down U Library */ 

SetU (Coinmand^ Response) ; 
if (Response [ 0 ] ) 

print f (''ERROR: Shut Down =* %x\n''. Response [0]); 


} 


/* 

* main • 

* Entry point 

ic 

*/ 

mainO 

{ 


/* 

* Initialize for NT simulation 
*/ 

init_U() ; 

/* 

* Update receive EOC for trinal checks only 
*/ 

Command[0] =» 14; 

Command [1] * NT; 

Command [2] » 2; 

SetU (Command/ Response) ; 
if (Response [ 0 ] ) 

print f ("ERROR: EOC Processing =» %x\n"/ Response [0]); 


/* 

* Issue Activation Command 
*/ 

print f ("Activating. . . ") ; 
f flush (stdout) ; 

Command [0] =4; 

Command [1] = NT; 

Command [2] = 1; 

SetU (Coinmand/ Response) ; 
if (Response [ 0 ] ) 

print f ("ERROR: Activate = %x\n"/ Response [0] ) ; 


/* 

* Wait 'till Link is up or Error 
*/ 


Command [0] - 9; 
do { 

SetU (Command/ Response) ; 
if (Response [ 0 ] =ERR_NOSTAT) 
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continue; 
if (Response [0] ) { 

print f ("ERROR: Link Status = %x\n"/ Response [0] ) ; 
printf ("AbortXn") ; 
reset^U () ; 
exit (0) ; 

}; 

} while ( ! (Response [ 1 ] & (LINKUP | ERROR) ) ) ; 


/* 

* Failure 
*/ 

if (Response [1] &ERROR) { 

printf ("Failure\n") ; 
reset_U 0 ; 
exit (0) ; 

} 

printf ("Successful\n") ; 
pause (SEC+1) ; 

/* 

* Flush activation EOCs 
*/ 

Command [0] =12; 
do { 

SetU (Command, Response) ; 
if (Response [0] ) 

print f ( "ERROR : Receive = %x" , Response [ 0 ] ) ; 
if (Response [ 1 ] ) 

printf ("Rx' edEOC [%x%x] Xn", Response [2] /Response [3] ) ; 
} while (Response [1] !=0) ; 

/* 

* Issue Deactivation Command 
*/ 

printf ("DeactivatingXn") ; 

Command [ 0 ] = 4 ; 

Command[l] = NT; 

Command[2] = 2; 

SetU (Command, Response) ; 
if (Response [0] ) 

printf ("ERROR; Deactivate = %x", Response [0] ) ; 


/* 

* Shut down U Interface and boogie 
reset_U() ; 
exit (0) ; 


} 
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TESNT.C This program verifies activation of the NT U transceiver and 

reception of EOC messages: i.e., that there is data flowing over the 
M channel. 


finclude 

<stdio.h> 


♦include 

"mtosux.h" 


♦define 

NT 

0 

♦define 

LT 

1 

^define 

LINKUP 

1 

♦define 

ERROR 

8 

♦define 

ERR_NOSTAT 

6 

unsigned 

char Command [20] , Response [20] ; 


/* 

^ init^U 

* Initializes and configs U-Board for LT simulation 

* 

*/ 

init_U() 

{ 

. Command[0] = 0; /* Initialize U Library */ 

SetU (Command/ Response) ; 
if (Response [ 0 ] ) 

print f ("ERROR: Init = %x\n"/ Response [0]); 


Command [ 0 ] = 1 ; 

Command [ 1 ] » 1 ; 

Command [2] ** 1; 

Command [3] = 0; 

Command [ 4 ] = 1 ; 

Command [ 5 ] =» 0 ; 

Command [6] = 0; 

Command [7] ~ 0; 

Command [ 8 ] = 0 ; 

Command [9] * 0; 

Command [10] =* 0; 

SetU (Command, Response) ; 
if (Response[0] ) 

print f ("ERROR: 


/* Config command */ 

/* LT simulation */ 

/* LT simulation */ 

/* U-law */ 

/* Internal Clocking */ 
/* No B1 routing */ 

/* No B2 routing */ 

/* No D routing */ 

/* Idle patterns */ 


= %x\n"/ Response [0]); 


} 


/* 

* reset^U 

* Shuts down U-Board 

* 


*/ 


reset_U() 

{ 

Command [0] * 30; /* shut down U Library */ 

SetU (Command, Response) ; 
if (Response [0] ) 

print f ("ERROR: Shut Down = %x\n", Response [0] ) ; 


} 
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/* 

* main 

* Entry point 

■k 

*/ 

main () 

( 


/* 

* Initialize for LT simulation 
*/ 

init_U() ; 

/* 

* Update receive EOC for trinal checks only 
*/ 

Command [0] ~ 14; 

Command [1] = LT; 

Command [2] = 2; 

SetU (Command, Response) ; 
if (Response [0] ) 

print f (^ERROR: EOC Processing = %x\n^, Response [0] ) ; 


/* 

* Issue Activation Command 
*/ 

printf ('^Activating . . ; 

fflush(stdout) ; 

Command[0] « 4; 

Command [1] » LT; 

Coinmand[2] = 1; 

SetU (Command, Response) ; 
if (Response [ 0 ] ) 

printf ('^ERROR: Activate « %x\n'', Response [0] ) ; 


/* 

* Wait 'till Link is up or Error 

Command [0] « 9; 
do { 

SetU (Command, Response) ; 
if (Response [ 0 ] =ERR_NOSTAT) 
continue; 
if (Response [0] ) { 

printf (''ERROR: Link Status = %x\n'', Response [0] ) ; 
printf ( "Abort Xn") ; 
reset^^U {) ; 
exit (0) ; 

} 

) while ( ! (Response [ 2 ]& (LINKUP I ERROR) ) ) ; 


/* 

* Failure 

if (Response [2] &ERROR) { 
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print f ("FailureXn") ; 

reset_U(); 

exit (0) ; 

} 

printf (^SuccessfulNn'^) ; 

/* 

* Send a 2B+D Loopback EOC 
*/ 

print f ('^Transmitting EOC [150]\n"); 

Command [0] =» 11; 

Command [ 1 ] = LT ; 

Command [2] = 1; 

Command [3] = 1; /* EOC address, dm */ 

Command [4] = 0x50; /* EOC info */ 

SetU (Command, Response) ; 
if (Response [ 0 ] ) 

print f ('^ERROR: Transmit = %x\n''. Response [0] ) ; 

/* 

* Send a Return to Normal EOC 
*/ 

print f ('^Transmitting EOC [lFF]\n''); 

Command [0] =11; 

Command [ 1 ] = LT ; 

Command [2] =1; 

Command[3] = 1; /* EOC address, dm */ 

Command [4] = OxFF; /* EOC info */ 

SetU (Command, Response) ; 
if (Response [ 0 ] ) 

print f (''ERROR: Transmit = %x\n'', Response [0] ) ; 
pause (SEC+1) ; 

/* 

* Flush the received EOCs (two of which are 150 and IFF) 

Command[0] = 12; 
do { 

SetU (Command, Response) ; 
if (Response [0] ) { 

print f ("ERROR: Receive = %x", Response [0] ) ; 
break; 

} 

if (Response [1] ) 

printf ("Rx'edEOC [%x%x] \n", Response [2] , Response [3] ) ; 
} while (Response [1] !=0) ; 

/* 

* Issue Deactivation Command 

* / 

printf ("DeactivatingXn") ; 

Command [ 0 ] = 4 ; 

Command [1] = LT; 

Command[2] = 2; 
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SetU (Command, Response) ; 
if (Response [0] ) 

printf ("ERROR: Deactivate = %x", Response [0] ) ; 

/* 

* Shut down U Interface 
*/ 

reset_D () ; 
exit (0) ; 
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B.15 ETSI LIBRARY 

The ETSI library is an optional C library which must be purchased 
in addition to the Chameleon 32 ‘C’ Development System. This 
library supports a total of 64 logical links. The library is named 
libetsi.a and resides in the a:\lib directory of the hard disk. 


Link Selection The ETSI library includes functions which enable you to control the 

use of 64 logical links. Each of the 64 links is referred to by a unique 
link number in the range 0 - 63. Each of the 64 logical links has its 
own SAPl and DC values, which are assigned as follows: 

When you select a link using setjink, you can then use the other 
functions to set the link on (s/on), set the link off {sloi), and transmit 
and receive messages. 

1. Use setjink io select one of the 64 links (0 - 63). All links 
default to state 9, disabled. 

2. Use setjsapi to assign the link a SAPl value. 

3. Use setjici, 2 and 3 to assign the link a DC value. 


Frame Status 

Word A two-byte, frame status (frstat) word is attached to the beginning 

of each received message. This field provides the following 
information: 

• Frame type 

• Number of link which received the frame 

• Command or response frame 

• Poll/Rnal bit value 

The get_rxstat function returns the low-order byte of frstat The 
gef_r//n/c function returns the high-order byte of frstat 

Addressing This library allows variable-length frame addressing. The range, 

conforming to CCITT Q.921 standards, is two (2) to four (4) octets. 
You can freely mix addressing modes in the 64 available logical 
links. 

To select 2-octet addressing, 

set LIC2 Ito any invalid value (>127) 

To select 3-octet addressing, 

set LIC3 to any invalid value 

To select 4-octet addressing, 

set ail LICs to va/Zd values. 
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SiMAN 


If two or more links have the same address (SAPI/LIC combination), 
received frames will be considered to belong to the highest link 
number matching that address. 

A link is disabled by selecting the link and setting the SAPI or UC1 
to an invalid value. You should ensure that the link is in the 
disconnected state before you disable it. If a link is disabled while 
in a connected (muiti-frame) state, the device under test will see it 
as a Layer 1 failure. 

Setting the SAPI and/or L1C1 value to an invalid value sets the link 
to the disabled state (9). This provides an easy means of testing 
lost-link recovery and ignoring unused links. 

The Frame Address format may be modified by the values in LIC2 
and L1C3. If an invalid value (>1 27) is set in LIC2, only the SAPI and 
LIC1 will be used. If LIC3 is set to an invalid value and LIC2 is valid, 
SAPI, LIC1 and LIC2 will be used. 

There are two functions which get the state of a link: statusQ gets 
the state of the selected link; link_$tat gets the state of any specified 
link. 

gei_freelink returns the number of the lowest-numbered, disabled 
link, findjink returns the number of the lowest link matching a 
specified SAPI/LIC combination. 


This library functions with Simultaneous Analysis (SIMAN) only if 
your Chameleon is equipped with a P5 board of revision level K33 or 
higher. If your Chameleon has an older P5 board (rev. K32 or 
lower), this feature is automatically disabled. You can obtain an 
upgrade kit from Tekelec which - when installed - will enable these 
older machines to run SiMAN with this library. 
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Functions 


The following functions are in the ETSI library. Also refer to the 
common functions and error codes described in Appendix B.1. 
Programming tips and examples are provided beginning on page 
B. 15-51. 


findJinkO B.15-4 

getJreelinkO B.15-5 

get_fwaiting B.15-6 

getJicIO B.15-7 

getjic20 B.15-8 

getjic3() 8.15-9 

getJinkO B.15- 10 

getjnksapi B. 15-11 

getjnklici B.15- 1 2 

getjnklic2 B.15-13 

getjnklic3 B. 15-1 4 

get_meswaiting 8.15-15 

get_i1ink0 B.15- 16 

get_rxstat() B. 15-1 7 

get_sapi() B.15- 18 

get_sconfig {) B. 1 5-1 9 

get_sim {) B. 15-20 

getjwindow B. 15-21 

initpl B. 15-22 

link_stat B. 15-23 

receive B. 15-24 

S_n200 B. 15-25 

S_n201 B. 15-26 

8_t200 B. 15-27 

S_t203 B. 15-28 

setjici B. 15-29 

setjic2 B. 15-30 

setjic3 B.15-31 

setjink B. 15-32 

set_net() B. 15-33 

setjsapi B. 15-34 

setjsconfig B. 15-35 

setjsubO B. 15-36 

set_tei() B. 15-37 

setjwindow B. 15-38 

setflg B. 1 5-39 

slof 0 B.15-40 

stonO B. 15-41 

start.sim B. 15-42 

statusO B. 15-43 

trans B.15-44 

transmit B. 15-45 

tnji : B.15-46 

trxcni ■ B.15-47 

tnddc B. 15-48 

trxidr B. 15-49 

trxmi B.15-50 
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findJinkO 


Declaration 


Description 


Returns 


int findjink(sapi, lid, Iic2, !ic3) 
int sapi, tei, tgi; 

sapi SAPI value of the link, in the rangeO-63 (SAPI > 63 is invalid, 
resulting in don’t care value) 

lie LICs 1 , 2 and 3 values of each link, in the range 0-127 (LIC/7> 
127 is invalid, resulting in don’t care value) 

Tfiis function returns the number of the lowest link matching the 
specified SAPI/LIC values. An invalid SAPI or LiC value is treated 
as a don't care for that parameter and returns the first link matching 
the valid parameters. 

0-63 Matching link number 

-1 No match found 
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g6t_free!lnk() 

Declaration 

Description 

Returns 


int get_freelink() 

This function gets the link number (0 - 63) of the first disabled link. 

0-63 Disabled link number 

-1 No free links available 

-2 initpl not performed 
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get_fwalting 

Declaration int get_fwaiting (Inkn) 

char Inkn; 

Range Inkn 0-63 

Description This function gets the number of l-frames waiting to be transmitted 

on link Inkn. 

Returns 0-7 Number of Wrames waiting to be sent by link 

Inkn 

See also the global error codes on page B.1-1 . 
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getJidQ 

Declaration 

Description 

Returns 


int getjid {) 

This function gets the L1C1 of the link currently under user control. 
Any value greater than 127 disables the link.' 

0-127 LICI for current link number 

1 28 - 255 LICI value that disables link. 

Also see global error codes on page B.1-1 . 
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get_lic2() 

Declaration 

Description 

Returns 


int 9etjic2() 

This function returns the LIC2 value of the iink currently under user 
control. 

0-127 LIC2 for current link number 

1 28 - 255 LIC2 value that disables use of LIC2 on the link 

(the link is not disabled) 

Also see global error codes on page B.1-1 . 
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getJicSQ 

DecSaration 

Description 

Returns 


int getjic3() 

This function returns the LIC3 value of the link currently under user 
control. 

0-127 UC3 for current link number 

1 28 - 255 LIC3 value disabling use of LIC3 on the link (the 
link is not disabled) 

Also see global error codes on page B.1-1 . 
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getJinkQ 

Declaration 

Description 

Returns 


int getJinkO 


This function gets the number of the link which is currently under 
user control. 

0-63 Current link number 

-1 initpl not performed 
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getjnksapi 

Declaration 

Range 

Description 

Returns 


int getjnksapi (Inkn) 
char Inkn; 

Inkn 0-63 

This function gets the SAP! value for link Inkn. 

0-63 SAPI value assigned to link Inkn 

> 63 SAPI value disabling link Inkn 

See also the global error codes on page B.1-1 . 
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getjnklid 

Declaration 

Range 

Description 

Returns 


int getjnklid (Inkn) 
char Inkn; 

Inkn 0-63 

This function gets the LIC1 value for link Inkn. 

0-127 LIC1 value assigned to link inkn 

>127 LICI value disabling link Inkn 

See also the global error codes on page B.1-1 . 
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getjnkiic2 


Declaration 

int getjnklic2{lnkn) 
char Inkn; 

Range 

Inkn 0-63 

Description 

This function gets the L1C2 value for link Inkn. if an invalid value 
(>127) is set in LIC2, only the SAPI and LIC1 (i.e., 2-byte 
addressing) will be used. 

Returns 

0-127 valid values 

>1 27 invalid values. 


See also the global error codes on page B.1-1. 
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getjnklic3 


Deciaration 


Range 

Description 


Returns 


int getjnklic3{lnkn) 
char Irikn; 

Inkn 0-63 

This function gets the LiC3 value for link Inkn. If LIC3 is set to an 
invalid value and LiC2 is valid, SAPI, LIC1 and LIC2 (i.e., 3-byte 
addressing) will be used. 

0-127 valid values 

>127 invalid values 

See also the global error codes on page B.1-1. 
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get_meswaiting 


Declaration 

Description 

Note 

Returns 


int get_meswaiting () 

This function gets the number of messages waiting to be received 
from the Front End Processor (FEP). 

This function returns the number of messages buffered by the FEP. 
The library buffers one additional message. 

0-32 Number of messages waiting to be received from 

the FEP 

See also the global error codes on page B.1-1 . 
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g6t_r!ink() 

Declaration 

Description 

Returns 


TEKBLEC 


int get_rlink() 

This function gets the number of the link which sent the last received 
message. This is the high order byte of the frame status word frstat 
passed by the FEP. 


0-63 

Current link number 

-1 

No messages received yet 

-2 

initpl not performed 
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get_rxstat() 



Declaration 

char get_n<stat() 


Description 

This function gets the low order byte of the frame status word frstat, 
which contains the frame type, C/R bit and P/F bit of the last 
received message. 

Returns 

0 - 0xC3 

OxFF 

OxFE 

frstat value (interpreted as shown below) 

No messages received yet 
initpl not performed 

Examples 

0x41 

0x02 

0xC3 

Non-final XID response 

Mrame command 

Final FRMR response 
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get_sapt() 

Declaration 

Description 

Returns 


int get_sapi{) 

This function gets the SAPI vaiue of the iink currentiy under user 
controi. 

0 - 255 SAPI for current link 

Also see global error codes on page B.1-1 , 
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get_sconfig () 

Declaration 

Description 


int get_sconfig () 

This function returns a copy of the current control configuration 
byte, which can be interpreted as shown in the figure below. 
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get_sim () 

Declaration 

Description 

Returns 


int get_sim () 

This function returns a copy of of the network/subscriber selection. 

0 Network 

1 Subscriber 
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get_window 

Declaration 

Range 

Description 

Returns 


int get_window (Inkn) 
char inkn; 

Inkn 0-63 

This function gets the number of outstanding Mrames on link 
number Inkn. 

0-7 Number of unacknowledged Mrames of link 

Inkn 

See also the global error codes on page B.1-1 . 
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initpl 

Declaration 

Description 

Note 

Ranges 

Returns 


int initpl (interface, sta, encode, bitrt) 
int interface, sta, encode; 
long bitrt; 

initpl loads the Front End Processor (FEP) code for the library and 
starts simulation. Predefined values exist in miklib.h to aid in setting 
up the call to this function, sta is the station type and selects the 
initial sense of the command/response bit. The library permits 
reselection of the station type at any time, encode selects the 
physical data encoding, bitrt sets the data rate when simulating a 
DCE device. 


This function is identicai to and interchangeable with the start_$im 
function. It has been included in the ETSI library for downward 
compatibility with the single link LAPD library. 


interface 


0 V-type interface (DCE) 

1 V-type interface (DTE) 

2 ISDN interface 


sta 0 NETWORK 

1 SUBSCRIBER 


encode 0 NRZ 

1 NRZI 

bitrt Any long integer value from 50 - 64000. 

See the global error codes on page B.1-1 . 
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link_stat 

Declaration 

Range 

Description 

Returns 


int link_stat(n) 
char n; 

n 0-63 

This function gets the current state of link n. 

0-9 Current state of link {see table below) 

See also the global error codes on page B.1-1 . 
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receive 

Declaration 

Description 


int receive(dest_acidr) 
char *dest_addr; 

This function receives a message from the FEP by performing the 
following tasks; 

• It polls the FEP to see if any received messages are available 

• It transfers the message contents to the user defined buffer 
pointed to by dest_adcSr 

• The total length of the message (including the frame status 
bytes frstat) is placed in the global variable rxien 

The frstat word is accessible by calling get_rlink and 
get_rxstat so that you can interpret and respond to a 
message quickly. The frstat bytes are attached to the 
beginning of each received message so that several 
messages may be received, sorted, interpreted, and 
individual responses made. 

it is up to the user to ensure that the destination buffer is long 
enough to contain the message. Generally, a length equal to N201 
+ 2 is adequate. 
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s_n200 

Declaration 

Range 

Description 

Returns 


int s_n200 (val) 
int val; 

val 1 - 255 

This function sets the maximum number of retries (N200). 

0 Successful 

See also global error codes on page B.1-1 . 
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s_n201 

Declaration 

Range 

Description 

Returns 


int s_n201 (val) 
int val; 

val 1-512 

This function sets the maximum length for an l-frame (N201). 

0 Successful 

See also global error codes on page B.1-1 . 
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s t200 


Declaration 


Range 

Description 


Returns 


int s_t200 (val) 
int val; 

val 0 — 255 

This function sets the time allowed for the remote station to respond 
(T200). Setting this value to 0 disables the T200 timer. 

0 Successful 

See also global error codes on page B.1-1 . 
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s t203 


Declaration 


Range 

Description 


Returns 


int s_t203 (val) 
int val; 

val 0-255 

This function sets the maximum time between frames (T203). On 
time out, a polled RR or XID command is transmitted, depending on 
the configuration selection. Setting this value to 0 disables the T203 
timer. 

0 Successful 

See also global error codes on page B.1-1 . 
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setjid 

Declaration 

Range 

Description 

Returns 


int setjid (value) 
char value; 

value The LIC1 value to use for the link, as follows: 

0-127 Valid LIC1 values 

128 - 255 Invalid LiCI value, which causes 
the link to be disabled 

This function sets the LICI value for the link under user control. 
LICI is a value assigned to, and may be associated with, a single 
link and a given point-to^oint data link connection. At any time, a 
given terminal endpoint { i E) may contain one or more LlCs. 

Normal values are: 

0-127 Valid 
128 - 255 Disable link 


0 

Successful 

-1 

Parameter out of range 

-2 

initpl not performed 

-<3 

Timeout 
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set iic2 


Declaration 


Range 


Description 


Returns 


int setjic2(valije) 
char value; 

value The LIC2 value to use for the link, as follows: 

0-127 Valid LIC2 values 

1 28 - 255 Disables the use of the LIC2 and 
L1C3 bytes 

This function sets the LiC2 value for the link under user control. If 
used, the LIC2 is the third byte of the LAPD Address field. Any value 
greater than 127 disables both LIC2 and LIC3. 

0 Successful 

-1 Parameter out of range 

-2 initpl not performed 

-3 Timeout 
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setjic3 

Declaration 

Range 

Description 

Returns 


int setjic3(value) 
char value; 

value The LIC3 value to use for the link, as follows: 

0-127 Valid LIC3 values 

128-255 Disables the use of the LIC3 byte 

This function sets the LIC3 value for the link under user control. If 
used, the LIC3 is the fourth byte of the LAPD Address field. Any 
value greater than 127 disables LIC3. 

0 Successful 

-1 Parameter out of range 

-2 initpl not performed 

-3 Timeout 


TEKB.EC 


B.15-31 


Version 1.0, November 1992 




Chameleon 32 ‘C’ Manual 


App. B.15; ETSl Library 


setjink 

Declaration 

Range 

Description 

Returns 


int setjink(n) 
char n; 

n 0-63 

This function puts link n under user control. Only one link at a time 
can be under user control. 

0 Successful 

-1 Parameter out of range 

-2 initpl not performed 

-3 Timeout 
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set_net () 

Declaration 

Description 


int set_net () 

This function sets the simulation side to NETWORK. The 
Chameleon can simulate either a network or subscriber device. 

When the Chameleon 32 emulates a network, it sends commands 
with the C/R bit set to one, and responds with the C/R bit set to zero. 
It sends the selected SAPI and LIC with the C/R bit automatically 
set in accordance with CCITT Q. 921 . 
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set_sapi 

Declaration 

Range 

Description 

Returns 


int set_sapi(v) 
char v; 

Accepted range of y is 0 - 255. A value over 63 disables the 
selected link. 

This function sets the SAPI value forthe link under user control. The 
SAPI (Service Access Point Identifier) indicates the layer two 
service type requested or supported. Normal values are: 



0 

Cali Control procedures 


16 

Packet communication procedures 


63 

Management procedures 


64 - 255 

Disable link 

0 


Successful 

-1 


Parameter out of range 

-2 


initpl not performed 



Timeout 
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set_sconfig 

Declaration 

Description 

Returns 


int set_sconfig (byte) 
int byte; 

This function sets the value of the control configuration byte, 
interpreted as shown in the figure below. 

0 Successful 

See also global error codes on page B.1-1 . 
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set_sub 0 

Declaration 

Description 


int set_sub () 

This function sets the simulation side to SUBSCRIBER. The 
Chameleon can simulate either a networ1< or subscriber device. 

When the Chameleon 32 emulates a LAPD subscriber, it sends 
commands with the C/R bit set to zero, and responds with the C/R 
bit set to one. It sends the selected SAPI and LIC with the C/R bit 
automatically set in accordance with CCITT Q. 921. 
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set_tef 

Declaration int set_tei(valu8) 

char value; 

Range value The TEI value to use for the link, as follows: 

0-127 Valid TEI values 

128-255 Invalid TEI value, which causes 
the link to be disabled 

Description This function sets the TEI value for the link under user control. TEI 

is a value assigned to, and may be associated with, a single link and 
a given point-to-point data link connection. At any time, a given 
terminal endpoint (TE) may contain one or more TEIs. 

This function is provided for the convenience of those users whose 
applications use the CCI7T Q.921 2-field address (SAPI TEI). Its 
use is completely interchangeable with set_lic1(). 

Normal values are: 

0-127 Valid 
1 28 - 255 Disable link 

Returns 0 Successful 

-1 Parameter out of range 

-2 initpl not performed 

-3 Timeout 
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set v/indow 


Declaration 

Range 

Description 

Note 

Returns 


int set_window (val) 
int val; 

val 1-7 

This function sets the maximum number of outstanding frames on 
each link. 

The total of outstanding frames + the number of frames passed to 
the FEP waiting to be transmitted + the number of messages over 
16 bytes long waiting to be received from the FEP may not exceed 
80. 

0 Successful 

See also global error codes on page B.1-1 . 


Version 1.0, November 1992 


TEKELEC 


B.15-38 





Chameleon 32 ‘C’ Manual 


App. B.15: ETSI Library 


setfig 

Declaration 

Range 

Description 

Returns 


int setfig (flag) 
int flag; 

flag 1 0x7E fill 

0 OxFF fill 

This function selects an interframe fill pattern. 

0 Successful 

See also global error codes on page B.1-1 . 
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Slot 0 

Deciaration 

Description 

Returns 


int slot 0 

This function sends a DISC and waits for a UA frame. This is 
equivalent to the CCITT primitive DL RELEASE. 

0 Successful 

Aiso see global error codes on page B.1-1 . 
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s3on 0 

Declaration 

Description 

Returns 


int slon () 

This function sends a SABME and waits for a UA frame. This is 
equivaient to the CCITT primitive DL ESTABLISH. 

0 Successful 

Also see global error codes on page B.1-1 . 
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start_sim 

Declaration 

Description 

Note 

Ranges 

Returns 


int start_sim (interface, sta, encode, bitrt) 
int interface, sta, encode; 
long bitrt; 

start_sim loads the Front End Processor (FEP) code for the libra^ 
and starts simulation. Predefined values exist in miklib.h to aid in 
setting up the call to this function, sta is the station type and selects 
the initial sense of the command/response bit. The libraiy permits 
reseiection of the station type at any time, encode selects the 
physical data encoding, bitrt sets the data rate when simulating a 
DCE device. 


This function is identical to and interchangeable with the initpl 
function, initpl is included for downward compatibility with the 
single link LAPD library. 


interface 

0 

V-type interface (DCE) 


1 

V-type interface (DTE) 


2 

ISDN interface 

sta 


0 NETWORK 


1 

SUBSCRIBER 

encode 

0 

NRZ 


1 

NRZI 

bitrt 


Any long integer value from 50 - 64000. 


See the global error codes on page B.1-1 . 
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statusQ 

Declaration 

Description 

Returns 


int statusO 

This function gets the current state of link under user control. 
0-9 Current state of link (see table below) 

See also the global error codes on page B.1-1 . 


TEKELEC 


B.15-43 


Version 1.0, November 1992 





Chameleon 32 ‘C’ Manual 


App. B.15: ETSI Library 


trans 

Declaration 

Description 


Returns 


int trans (frame, address, len) 
int frame, len; 
char ‘address; 

This function transmits a frame, as follows: 

frame selects type of frame to transmit: 

0x80 l-frame Sequenced (numbered) Mrame 

0x81 Ul • Unnumbered Wrame (NSI) 

0x82 XIDC XID command frame 

0x83 XIDR XID response frame 

address is a pointer to the first byte of the message to be 
transmitted. 

len is the actual length of the message to be transmitted. There are 
two restrictions on the message length: 

• Mrames should not exceed the value set in N201 (maximum 
length of an Wrame) 

• The total length of the frame cannot exceed 512 bytes. 

0 Successful 

Also see global error codes on page B.1-1 . 
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transmit 

Declaration 


Description 


Note 


Returns 


int transmit (xioc, xlen) 
char *xloc; 
int xlen; 

This function transmits a message in a sequenced (numbered) 
l-frame. 

xIoc is a pointer to the first byte of the message to be transmitted. 

xlen is the actual length of the message to be transmitted. There 
are two restrictions on the message length: 

• l-frames should not exceed the value set in N201 (maximum 
length of an l-frame) 

• The total length of the frame cannot exceed 512 bytes. 

The fransm/f function is provided for user convenience. If extremely 
high data rates are required, the trans function should be used, as 
it is somewhat faster. 

0 Successful 

Also see global error codes on page B.1-1 . 
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trut 

Declaration 

Description 

Note 

Returns 


int tru! (xioc, xlen) 
char *xloc; 
int xlen; 

This function transmits a message in an unnumbered l-frame (Ul 
frame). 

xioc is a pointer to the first byte of the message to be transmitted. 

xlen is the actual length of the message to be transmitted. The total 
length of the frame must not exceed 512 bytes. 

The fm/function is provided for user convenience. If extremely high 
data rates are required, the trans function should be used, as it is 
somewhat faster. 

0 Successful 

Also see global error codes on page B.1-1 . 
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trxcni 

Declaration 

Description 

Returns 


int trxcni () 

This function transmits an XID command frame with no data field. 

0 Successful 

See also global error codes on page B.1-1 . 
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trxidc 


Declaration 


Description 


Note 


Returns 


int trxidc (xioc, xlen) 
char 'xIoc; 
int xlen; 

This function transmits a message in an XID command frame. 

xioc is a pointer to the first byte of the message to be transmitted. 

xlen is the actual length of the message to be transmitted. The total 
length of the frame must not exceed 512 bytes. 

The trxidc function is provided for user convenience. If extremely 
high data rates are required, the fra/7s function should be used, as it 
is somewhat faster. 

0 Successful 

Also see global error codes on page B.1-1 . 
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trxidr 


Declaration 


Description 


Note 


Returns 


int trxidr (xioc, xlen) 
char *xloc; 
int xlen; 

Transmit a message in an XID response frame. 

xIoc is a pointer to the first byte of the message to be transmitted. 

xlen is the actual length of the message to be transmitted. The total 
length of the frame must not exceed 512 bytes. 

The trxidc function is provided for user convenience. If extremely 
high data rates are required, the frans function should be used, as it 
is somewhat faster. 

0 Successful 

Also see global error codes on page B.1-1 . 
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trxrni 

Declaration 

Description 

Returns 


int trxrni () 

This function transmits an XID response frame with no data field. 

0 Successful 

See also global error codes on page B.1-1 . 
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PROGRAMMING NOTES AND EXAMPLES 

This section provides general information about using the ETSI 
library. 


General Notes In your program, specify the Chameleon port being used by a call to 

the sefjDorf function. This is not absolutely necessary when using 
a Single-Port Chameleon (Ch20), but should be done to make your 
application portable. 

Acalltoinitpl must be made to start the Front End Processor (FEP). 
This loads the FEP operating code and starts the simulation. The 
Chameleon is then ready to begin testing. 

Before frames can be transmitted or received, at least one link must 
be enabled. To do this: 

a. Use seM/n/c to select a link (default is 0) 

b. Set the SAPI and LIC1 to valid values by calling set_sapi and 
setjic 

c. LIC2 and LiC3 must be set to a valid value if they are to be 
used. 


Interpreting 

Received 

Messages To interpret a received message, you must know the SAPI value 

and the frame type of the received message. This information is 
available to you from the frame status bytes, and can be accessed 
using the technique shown below: 

rec9ive(pointr); 

if(rxlan s s 0) /*exit if no message received*/ 

return(0); 

frtypes(get_rxsta()&3); /*get the frame type status bits*/ 
lnksget_rlink(); /*get number of the iink sending message*/ 

sapvaisgetjnksap(ink); /*get the SAPI for that iink*/ 

In this example, the frame type may be interpreted from frtype as 
follows: 

0 « Ul frame 

1 ■ XID frame 

2 » Mrame 

3 - FRMR 

sapval is the SAPI value assigned to the link on which the message 
was received. 
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Optimizing 
Transmit Speed 


Transmitting 

Responses 


To optimize speed for applications such as load generators, follows 

these guidelines: 

• The trans function is faster than the other transmit functions 
such as transmit, trui, trxidr, and trxidc. 

• If you are not concerned with the contents of the received 
messages, use the following technique to keep the receive 
buffer empty. Thisisfasterthanacalitotherece/vefunction in 
the transmit loop. 

if(get_meswtg()>=6) 

flushQ; 

• Minimize input, output, and screen print operations in ail 
tasks. Since the processor that runs the C shell also manages 
many of the I/O tasks, this will result in your simulation 
program running faster. 

• Run your program in background mode. This is done by 
adding an ampersand (&) at the end of the file name when 
starting the test from the C shell. For example: 

test& 

will run the program test in background mode. This causes 
the program to run at a higher priority and frees the C shell for 
other uses. This technique also reduces the number of 
windows available for other tasks, since a separate window is 
opened for each program running in background mode. 


In a test environment, the actual information content of a given 
message type is often fixed. In such cases, only the message type 
must be known in order to select the proper response. To simplify 
responding to message, predefine the content of responses in a 
message array. 

In the following program fragment, the following is assumed: 

• A set of responses and pointers to the responses has been 
defined earlier 

• SAPI/LIC combinations have been set up 
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The program fragment uses a defined. value TYPEOS, which is the 
offset to the byte in the message containing the message type. The 
cal! to fix_cref extracts the call reference value from the received 
message and copies it into the selected response message. 

respondO 

{ 

char mestyp,*resp; 
int respjen; 

rxlensO; /* prepare to loop until message received */ 
while(!rxlen) 

receive(&rxmes[0]) ; 

i^(get_rxstat()&3)=2) /*only respond to Iframes*/ 

{ 

mestypsrxmesfTYPEOS]; /*get message type from rcvd message'/ 
switch(mestyp) 

{ 

case CALL.SU: 

/'if msg is call setup*/ 

/'respond setup ack*/ 
resps&su_ack; 
respJen=SU_ACK_LEN; 
break; 

e 

e 

e 

case RELEASE: 

/* if msg is release*/ 

/'respond release complete*/ 
resp=&rel_cmplt; 
respJen=REL_CMPLT_LEN; 

} 

fix_cref(resp); /'set response call ref value*/ 
setjinki[get_rlink()); /'select link to send response*/ 
transmit(resp, respjen); /* send response*/ 

} 

flx_cref(dest) 

char *dest; 

{ 

Int ref_val; 

refvabrxmes[CREF_OS]; 

*(dest-i>CREF_OS-2)srefval; /*-2 to allow for frstat bytes*/ 
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Demonstration Programs 

You can run the two test programs for ETSI LAPD library 
port-to-port on a dual-port CH32. You can also run them between 
Chameleons - CH32-to-CH32. However, in this case you may 
have to change the port selection in the function sim_start(} at the 
end of the program. 

To compile and link these programs: 

cc -o etsia etsia.c -letsi 
cc “O etsib etsib.c -letsi 

Start the ‘etsia’ program first. 
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ETSIA.C 


etsia.cis one of two sample programs to demonstrate the use of the 
ETSi lapd library functions. 

The Program : 


#include <stdlo.h> 
#include <cham.h> 
#include <ctype.h> 
#include <fcntl.h> 
^include <init.h> 
#include <video.h> 
#include <mtosux.h> 

char tmsg[48],rmsg[48]; 


main() 


char insit, *tadr,*radr,answer; 
extern char ‘mallocQ; 
extern int rxlen; 
int result,tempi; 

long int count; 

printf(”C program started.\n”); 
tadrs&tmsg[01; 
radr=&rmsg[0]; 
sim_start(); 


/*•*** make and display transmit message ****•/ 

for(insit=0;insit<=16;insit4~i-) 

tmsg[insit] a insit; 

printf(”message s ”); 
for(insits0;insit<=1 6;insit4-+) 

printf(” %0x ”,tmsgrinsit]); 
pr!ntf(”\n”); 


/•**** do frame level setup *****/ 

result = setflg(O); 
result s set_mod(1); 
result s s t200(0); 
result s s_t203(0); 
result s s_n201(260); 
result s s_n200(26); 
result s set_wlndow(3); 


/*•*** setup sapi and LICs for 64 links and set them on *****/ 

tempi s get_freelink(); 
if(templ<0) 
break; 

result s setjink(tempi); 
result = set_sapi(tempi); 
result s setjldftempl); 
result s setjic2(tempi); 
results set Ilc3(tempi); 

pause<5+5l2); /* so other tasks can use processor */ 

} 
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while(status() <4 ) 

pause(5->-512}; /* so other tasks can use processor */ 

/**•** send and receive until ’q’ is entered *****/ 

result = setjink(2); 
countsO; 

result = get_link(); 
printf(”Current link is %d \n”,result); 

prlntf(”\033(2J”); 
printf(” type Q to quit\n”); 

for(;;){ 

answersgetch(_std vt) ; 

if(answer == ’q’) break; 
result = receive(radr); 
if(rxien>0) 

{ 

printf(”\033[10;7f received message = ”); 
for(insitsO;insit<rxlen;insit++) 

prlntf(” %0x ”,rmsg[insit]); 
pfintf(”\n\n”); 

printf(”Current link is %d \n”,get_rlink(}); 

resuit s set Jink(get_rlink()}; 
if(status()3s4) 

result = trans(0x80,tadr,1 5) ; 
count-M-; 

printf(”M)33r%d;%df”, 14,36); 
printf(”\033t3lmThat's %ld. \n”, count); 

^ause<517); /* so other tasks can use processor */ 

for(counts0;count<0xfff;count+4); 

/•*•*• if link still connected, disconnect it, then exit **”*/ 
if(status<)>0) 

result s siofO; 

} 


} 

simjstartO 

" t 


int rets/et2; 
long int rate; 

rates64000; 

printfr'P’ying to start PI”); 
retss initpl(0,0,0,rate); 
printf(” result a %0x\n”,rets); 

} 
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ETSIB.C 


etsib.cls one of two sample programs to demonstrate the use of the 
ETSI lapd library functions. 

The Program : 

#include <stdio.h> 

^include <cham.h> 

#include <ctype.h> 

#include <fcntl.h> 

#inciude <init.h> 

#include •svideo.h> 

char tmsg[48],rmsg[48]; 
mainO 


chartempc,insit,userjn,*tadr,*radr; 
extern int rxlen; 
int result, tempi; 
long int count; 

printf(”C program started.\n”); 
tadr3&tmsg[0]; 
radrs&rmsg[0]; 
sim_start(); 

/••*** make and display transmit message **“*/ 

for(insitsO;insit<sl 6;insit++) 

tmsg(insit] s 1 6-insit; 

printf(”message s ”); 
for(insits0;insit<s16;insit-i"»-) 
printf(” %0x ”,tmsg[insit]}; 
printf(”\n”); 

/*•«* do frame level setup *•**•/ 

result=set_mod(1 ); 
resultss_t200(0); 
resultss_t203(0h 
resultss_n201 (20); 
resuitsset_window(3); 

/*•*** setup sapi and LICs for 64 links and set them on *•***/ 

-Jor(;;) 

tempi=get_freelink(}; 

if(tempi<0) 

break; 

printf(”free link s %d\n”, tempi); 
result s setjink(tempi); 
result s set~sapi(tempi); 
result s setjicl(tempi); 
result s set~lic2(tempi); 
result s setjlc3(tempi); 
result s slon(); 
while(status<) < 4) 

paus^S13); /* so other tasks can use processor */ 
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/*•*** send and receive until user types ’Q’ ***"/ 

result=set_link(2); 

countsO; 

result=getjink(}; 

printf(”Current link is %d \n”, result); 
result=trans(0x80,tadr,1 5); 


printf(”\033[2J”); 

printfr type Q to quit, S to restart link, T to transmit lframe\n”); 


for(;;){ 

userJn=toupper(getch(_stdvt)); 

if(userJnss:’T’) 

7esultstrans(0x80,tadr,1 5); 
if(user inss’Q’) 

Itreak; 

if(userjn == ’S’) 
slonO; 

result=receive{radr}; 

if(rxlsn>0) 

printf(’’\033{10;8f received message s ”); 
K)r(insits:0;insit<rxlen;insit-H-) 

printf(’’ %0x ".rmsglinsit]); 
printf(’’\n\n’’); 

printf(”Current link is %d \n”,get_rtink()); 


tempcsget_riink()ss63? 0:get_rlink(>i-1 ; 
resultsset link(tempc); 
if(status(lss4) 

resuitstrans(0x80,tadr,1 5); 
count<M-; 

prlntf(”\033r%d;%df ”,1 4,36); 
printf(”\033[36m That’s %Ia.\n”,count); 

} 

^ause(5l3); /* so other tasks can use processor V 

for(countsO;count<Oxfff;count++); 

/•••*• if link still connected, disconnect it, then exit *"**/ 
if(status()>0) 

resultsslofO; 

printf("slof result %0d\n’’, result); 

} 


sim_start() 

Int rets,ret2; 
long int rate; 

retsssetport(PORTB); 

rates64000; 

^ "Trying to start PI ”); 

nitp1(1,1,0,rate); 
printf(" result s %0x\n”,rets); 

} 
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& (Background Mode), 2.1-5 
# (Remark), 2.1-6 
’ (Echo Text), 2.1-7 
abs, 5.2-1 
access, 5.2-2 
Activation, 

Set U-Transceiver, B.14-6 
Acquisition, Data, 5.1 Off 
ailoca, 5.2-3 

Anaiysis Library, App. BIO 
Functions: 
init_anal, B.10-2 
getevent, B.10-5 
reset_anal, B.10-7 
Assigning port functions, 

AUX1, 5.7-1 thru -6 
AUX 2, 5.7-7 thru -11 
Debugger, 2.1-2 
Async Library, App. B9 
Functions: 
flush, B.1-3 
getphy, B.1-4 
getport, B.1-6 
getime, B.1-6 
initpl , B.9-2 
initime, B.1-7 
pi reset, B.1-8 
receive, B.9-4 
setleds, B.i-9 
setphy, B.1-10 
setport, B.1-11 
settimer, B.1-12 
tbreak, B.9-6 
timer, B.1-13 
transmit, B.9-6 
tready, B.9-7 
atof, 5.2-4 
atoi, 5.2-5 
atol, 5.2—6 
Aux Serial Port 1 
Using, 5.7-1 
Functions: 
initporlb, 5.7-2 
recpb, 5.7-4 
rstdrvb, 5.7-5 
sendpb, 5.7-3 
Aux Serial Port 2 
Using, 5.7-1 
Functions: 


initporta, 5.7-7 
recpa, 5.7-9 
rstdrv, 5.7-1 0 
sendpa, 5.7-8 

B 

BAS_VERSiON, B.6-2 
Basic Rate Interface Library, App. B6 
bas_version, B.6-2 
setbasic, B.6-3 
batch, 2.1-8 
Batch Files 

batch command, 2.1-8 
login file, 2.1-1 
bcmp, 5.2-6 
bcopy, 5.2-6 
BERT functions, 5.10-1 ff. 
blockjen, 5.10-4 

Boards, Command (See U-Board) 
BOP Library (libbop.a), App. B1 
Functions: 
flush, B.1-3 
getphy, B.1-4 
getport, B.1-5 
getime, B.1-6 
initpl , B.2-2 
initpl _8k, B.2-3 
initime, B.1-7 
pi reset, B.1-8 
receive, B.2-4 
setfig, B.2-6 
setleds, B.1-9 
setphy, B.1-10 
setport, B.1-11 
settimer, B.1-12 
timer, B.1-13 
transmit, B.2-6 
tready, B.2-7 

BSC Library (libbsc.a), App. B7 
Functions: 
flush, B.1-^ 
getphy, B.1-4 
idle_,mode, B.7-2 
initpl , B.7-3 
initime, B.1-7 
pi reset, B.1-8 
receive, B.7-4 
setphy, B.1-10 
setfwrt, B.1-11 
settimer, B.1-12 
timer, B.1-13 
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transmit, B.7-5 
tready, B.7-6 
bzero, 5.2-6 


c 

C Library (libc.a), Chapter 5 
Error Messages, 2.1-31, 2.8-1 
Control Characters, 5.6-1 
Back space, 5.6-1 
Beil, 0.6—1 

Carriage return, 5.6-1 
Cursor down, 5.6-1 
Cursor right, 5.6-1 
Line feed, 5.6-1 
Functions: 
abs, 5.2-1 
access, 5.2-2 
alloca, 5.2-3 
atof, 5.2—4 
atoi, 5.2—5 
atol, 5.2-5 
bcmp, 5.2-6 
bcopy, 5.2-6 
bzero, 5.2-6 
cailoc, 5.2-7 
cap__disable, 5.10-2 
cap_enable, 5.10-2 
cap_set, 5.10-3 
cap_status, 5.10-3 
clearerr, 5.2-8 
close, 5.2-9 
creat, 5.2-10 
execi, 5.2-11 
execv, 5.2-12 
exit, 5.2-13 
_exit, 5.2—13 
fclose, 5.2-14 
terror, 5.2-15 
feof, 5.2-16 
fflush, 5.2-17 
fgetc, 5.2-18 
fgets, 5.2-19 
fileno, 5.2-20 
fopen, 5.2-21 
fprintf, 5.2-38 
fputc, 5.2-22 
fputs, 5.2-23 
fread, 5.2-24 
free, 5.2-25 
freopen, 5.2-21 
fscanf, 5.2-62 


fseek, 5.2-26 
ftell, 5.2-27 
fwrite, 5.2-28 
getc, 5.2-29 
getchar, 5.2-30 
gets, 5.2-31 
getw, 5.2-32 
isainum, 5.2-33 
isalpha, 5.2-33 
isascii, 5.2-33 
iscntrl, 5.2-33 
isdigit, 5.2-33 
islower, 5.2-33 
ispiint, 5.2-33 
ispunct, 5.2-33 
isspace, 5.2-33 
isupper, 5.2-33 
isxdigit, 5.2-33 
ioaddtd, 5.10'4 
longjmp, 5.2-35 
Icalloc, 5.2-7 
Imailoc, 5.2-36 
Irealloc, 5.2—49 
iseek, 5.2-34 
mailoc, 5.2-36 
onexit, 5.2-37 
open, 5.2-38 
perror, 5.2—42 
printf, 5.2-39 
putc, 5.2—43 
putchar, 5.2—44 
puts, 5.2—45 
putw, 5.2—46 
qsort, 5.2-47 
rand, 5.2—48 
read, 5.2-49 
reaiioc, 5.2-50 
rename, 5.2-51 
saveacq, 5.10-5 
savedtd, 5.10-6 
rewind, 5.2-52 
scant, 5.2-63 
setbut, 5.2-66 
setbufter, 5.2-66 
setjmp, 5.2-67 
setlinebuf, 5.2-66 
sprintf, 5.2-39 
srand, 5.2-48 
sscant, 5.2-53 
startdtd, 5.10-7 
startdtd, 5.10-7 
street, 5.2-58 
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strcmp, 5.2-58 
strcpy, 5.2-58 
strncat, 5.2-58 
strlen, 5.2-58 
strncpy, 5.2-68 
strncmp, 5.2-58 
stopdfd, 5.10-8 
stopdtd, 5.10-8 
-tolower, 5.2-60 
toupper, 5.2-60 
ungetc, 5.2-61 
unlink, 5.2-62 
write, 5.2-63 
strtol, 5.2-6 
toascii, 5.2-60 
tolower, 5.2-60 
xtrcap, 5.2-58 
xtrcpy, 5.2-58 
xtrncpy, 5.2-68 
Globals, 5.3—1 
C Shell, Chapter 2.1 
C Shell Commands: 

& (Background Mode), 2.1-5 

# (Remark), 2.1-6 

’ (Echo Text), 2.1-7 

batch, 2.1-8 

cat, 2.1-9 

cd. 2.1-10 

cp, 2.1-11 

ctags, 2.1-12 

dump,2.1-13 

exit, 2.1-14 

format, 2.1-15 

getenv, 2.1-16 

help, 2.1-17 

jobs, 2.1-18 

kill, 2.1-19 

Is, 2.1-20 

man, 2.1-21 

mkdir, 2.1-22 

mkres, 2.1-23 

more, 2.1-24 

mv, 2.1-25 

pwd, 2.1-26 

rm, 2.1-27 

rmdir, 2.1-28 

rmres, 2.1-29 

run, 2.1-30 

setenv, 2.1-31 

shell, 2.1-32 

size, 2.1-33 

time, 2.1-34 


calloc, 5.2-7 
cap_disable, 5.10-2 
cap_enable, 5.10-2 
cap_set, 5.10-3 
cap_status, 5.10-3 
cat, 2.1-9 
cd, 2.1-10 

character arrays, B.1 4-1 
ciearerr, 5.2-8 
close, 5.2-9 
clr_pream, 5.10-4 
Codes, Error, B.1 4-2 
Compiler, Chapter 2.2, 4 
Commands: 
cc, 2.2-1 
mcc, 2.2-^ 

Limits, App. A 

Machine Dependencies, 4.1-1 
Data Elements, 4.1-1 
External Names, 4.1-1 
Include file, 4.1-2 
Registers, 4.1-2 
Processing, 4.2-1 
Error Processing, 4.2-1 
Code Generation, 4.2-1 
Configuration, of Ch32, 2.1-1 
Commands - 
DBGPORT, 2.1-2 
REM, 2.1-1 
Operands, 

AUX1, 2.1-2 
OFF, 2.1-2 
VT, 2.1-2 

Configure, U interface, B.1 4-3 
Connection, Get Transceiver, B.1 4-6 
cont_run, 5.10-5 
cp, 2.1-11 
creat, 5.2-10 
- ctags, 2.1-12 


D 


Debugger port, assigning (See under A) 
Device files, 2.1-1 
Disassembler, Chapter 2.5 
dis command, 2.5-1 
Error Messages, 2.5-2 
double get_err_rate, 5.10-17 
dump,2.1-13 
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E_ 

Egrep, Chapter 2.6 
Error Messages, 2.6-4 
Examples, 2.6-3 
Introduction, 2.6-1 
Usage, 2.6-1 

Environmental variables, 2.1-3 
getenv, 2.1-15 
setevn, 2.1-28 

BC (background color), 2.1-28 
FC (foreground color), 2.1-28 
HOME, 2.1-28 
PATH, 2.1-28 
YEAR, 2.1-28 
User-defined, 2.1-28 
error_off, 5.10-13 
error_on, 5.10-13 
Errors, 

Get U- transceiver, B.14-7 
Set U-transceiver, B.14-7 
execi, 5.2-11 
execv, 5.2-12 

exit (shell command), 2.1-14 
exit (C function), 5.2-13 
Extensions, App. A 


F 

fclose, 5.2-14 
terror, 5.2-15 
feof , 5.2-1 6 
ftiush, 5.2-17 
fgetc, 5.2-18 
fgets, 5.2-19 

File Functions (low level), 5.8-1 to 5.1-8 
Filename substitution, 2.1-2 
*, 2 . 1-2 
[ 1 . 2 . 1 - 

fiieno, 5.2-192 
find Jink, B.11-4 
flush, B.1-3, B.13-9 
flush all, B.13-10 
Fmkdir, 5.8-4 
fopen, 5.2-21 
format, 2.1-15 
fprintf, 5.2-38 
fputc, 5.2-22 
fputs, 5.2-23 
fread, 5.2-23 
free, 5.2-25 


freopen, 5.2-21 
Frmdir, 5.8-5 
fscanf, 5.2-52 
Fsearch, 5.8-6 
fseek, 5.2-26 
ftell, 5.2-27 
fwrite, 5.2-28 


G 

get_freellnk(), B.11-5, B.12-4 
get_fwaiting, B.11-6, B.12-5 
get Jink, B.11-7, B.12-6 
getjli, B.12-7 
getjnklli, B.12-8 
getjnksapi, B.11-8 
getjnktei, B.11-9 
getjnktgi, B.11-10 
get_meswaiting, B.11-11, B.12-9 
get-mod, B.3-4 
get_riink, B.11-12, B.12-10 
get-rntei, B.3-5, B.11-13 
get-rsapi, B.3-6, B.11-14 
get_rxstat, B.11-15, B.12-11 
get_sapi, B.11-16 

get-sconfig, B.3-7, B.11-17, B.12-12 

get-sim, B.3-8, B.11-18 

getjei, B.11-19 

getjgi, B.11-20 

get_window, B.11-21, B. 12-1 3 

getc, 5.2-29 

getchar, 5.2-30 

getenv, 2.1-16 

getevent, B.10-5 

getime, B.1-6 

getphy, B.1-4 

getport, B.1-5 

gets, 5.2-31 

getw, 5.2-32 


H 

HOLC Library (libhdic.a), App. B2 
Functions: 

Ch32, configuring, 2.1-1 
flush, B.1-3 
getphy, B.1-4 
getport, B.1-4 
getime, B.1-6 
Initpl , B.4-1 
inittime, B.1-7 
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p1 reset, B.1-8 
receive, B.4— 3 
set-n1, B.4-4 
set-n2, B.4-5 
set-t1, B.4-6 
set-window, B.4-7 
setleds, B.1-9 
setphy, B.1-10 
setport, B.1-11 
settimer, B.1-12 
slot, B.4-3 
slon, B.4-9 
status, B.4-10 
timer, B.1-13 
transmit, B.4-11 

Multi-Link (See Multi-Link HDLC) 
help, 2.1-17 


I 


init_a, B. 13-11 
Initialize, U interface, B.1 4-3 
init_anai, B.1 0-2 
init_b, B.1 3-1 2 
initporta, 5.7-2 

initp1,B.2-2, B.3-9, B.4-2, B.5-2, 
B.7-2, B.9-2, B.1 1-22, ' 
B.12-14. B.13-13 
Initp1_8k, B.2-3 
inittime, B.1 -7 
isainum, 5.2-33 
isaipha, 5.2-33 
isascii, 5.2-33 
iscntri, 5.2-33 
isdigit, 5.2-33 
isiower, 5.2-33 
isprint, 5.2-33 
ispunct, 5.2-33 
isspace, 5.2-33 
isupper, 5.2-33 
isxdigit, 5.2-33 
I/O Redirection, 2.1-3 
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jobs, 2.1-18 


K 

kill, 2.1-19 


L 

Language Extensions, 4.5-1 
Assembler, 4.5-1 
C Objects, 4.5-2 
Character Constants, 4.5-5 
Defaults. 4.5-2 

Forward Pointer References, 4.5-4 
Global Symbols, 4.5-2 
Structure Assignment, 4.5-5 
Syntax, 4.5-1 

LAPD Library (liblapd.a), App. B3 
Functions; 
flush, B.1 -3 
get-mod, B.3-4 
get-rntei, B.3-5 
get-rsapi, B.3-6 
get-sconfig, B.3-7 
get-sim, B.3-8 
getphy, B.1 -4 
getjwrt, B.1 -5 
getime, B.1-6 
initpl , B.3-9 
inittime, B.1-7 
pi reset, B.1-8 
receive, B.3— 10 
restartsim, B.3-12 
setfig, B.3-13 
setleds, B.1-9 
set-bit-rate, B.3-14 
set-mod, B.3-15 
s-n200, B.3-16 
s— n201 , B.3— 1 7 
set-net, B.3-18 
set— mtel, B.3— 1 9 
set-rsapi, B.3-20 
set-sapi, B.3-21 
set-sconfig, B.3-22 
set-sub, B.3-24 
s-t200, B.3-25 
s^03, B.3-26 
set— tei, B.3— 27 
set-window, B.3-28 
setleds, B.1-9 
setphy, B.1-10 
setport, B.1 -5 
settimer, B.1-12 
slot, B.3-29 
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slon, B.3— 30 
status, B.3-31 
stopsim, B.3-32 
timer, B.1-13 
trans, B.3-33 
transmit, B.3-34 
trui, B.3-35 
tn<cni, B.3-36 
TRXRNI, B.3-<37 
TRXIDC, B.3-38 
TRXIDR, B.3-39 
icalloc, 5.2-7 

Librarian, Chapter 2.4, App. A 
ar command, 2.4-2 
Error Messages, 2.4-3 
Library Implementation, Chapter 4.4 
Line Separators, 4.4-1 
Memory Aiiocation, 4.4-1 
iink_stat, B.11-23, B. 12-1 5 
Linker, Chapter 2.3, App. A 
Errors, 2.3-3 
Id command, 2.3-1 
Object File Format, 2.3-5 
Process, 2.3-4 
Imalioc, 5.2-36 
Loading C, 1.2-1 
login file, 2.1-1 
long get_blkerrs, 5.10-17 
long get_errsec, 5.10-18 
long get.rbiterrs, 5.10-19 
long get_rbits, 5.10-18 
long get_tbiterrs, 5.10-21 
long get__tbits, 5.10-19 
long get_runtime, 5.10 - 20 
long get_serrsec, 5.10-20 
long get_syncloss, 5.10-21 
longjmp, 5.2-35 
Irealloc, 5.2-49 
Is, 2.1-20 
Iseek, 5.2-34 


M 


M channel, 

Configuring for, B.14-3 
Receive data over U interface, B. 14-10 
Transmit data over U interface B.1 4-9 
malloc, 5.2-36 
Make Utility, 3.1-1 
Dynamic dependency, 3.1-7 
Examples, 3.1-11 


Macro definition, 3.1-6 
Makefile structure, 3.1-3 
Suffixes table, 3.1-8 
Transformation rules, 3.1-9 
Math Library (libm.a). Chapter 5.5 
Description, 5.5-1 
Functions: 

Absolute value, 5.5-2 
Exponential, 5.5-2 
Factorial, 5.5-2 
Logarithm, 5.5-2 
Matrix inverse, 5.5-3 
Transcendental, 5.5-2 
Square, 5.5-2 
Square root, 5.5-2 
man, 2.1-21 

Messages, U interface, B.1 4-9, -10. 
mkdir, 2.1-22 
mkres, 2.1-23 
mihjlush, B.13-14 
mlh_receive, B.1 3-1 5 
mlh_set_n1 , B.1 3-1 6 
mlh_set_n2, B.1 3-1 7 
mlh_set_net, B.1 3-1 8 
mlh_set_sub, B.1 3-1 9 
mlh_set_t1 , B. 1 3-20 
mlh_set_t2, B.13-21 
mlh_set_wlndow, B. 1 3-22 
mlh_slof, B.1 3-23 
mlh_sion , B.1 3-24 
mlh_status , B.1 3-25 
mlh_trans, B.1 3-26 
Mode Control, 

EOC, B.14-11 
M4, B.1 4-1 2 
M5/6, B.1 4-1 2 
more, 2.1-24 

Multi-Link HDLC (iibmhdic.a) App. B.1 3 
Functions: 
flush, B.1 3-9 
flush_ail, B.1 3-10 
init a, B.1 3-11 
iniCb , B.1 3-1 2 
initpl , B.1 3-1 3 
mihjiush, B.13-14 
' mih_receive, B.1 3-1 5 
mlh__set_n1, B.1 3-1 6 
mlhjset_n2, B.1 3-1 7 
mlh_set_net, B.1 3-1 8 
mih_set”sub, B.1 3-1 9 
mih~set_t1, B.1 3-20 
mih set t2, B.13-21 
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mlh_set_winciow, B. 13-22 
mlh_slof, B. 13-23 
nnlh_slon (port), B. 13-24 
nnlh_status , B. 13-25 
mlh_trans, B. 13-26 
receive, 3.13-27 
set_n1, B. 13-28 
set_n2, B. 13-29 
set_net (), B.13— 30 
set_pat, B. 13-31 
set_ratio, B. 13-32 
setjl, B. 13-33 
set_t2, B. 13-34 
set_sub (). B.13-35 
set_window, B. 13-36 
slot 0, B.13-437 
Sion 0, B. 13-38 
status (), B. 13-39 
transmit, B. 13-40 

Multi-Link LAPD (libmiapd.a) App. B.11 
Functions: 
findjink, B.11^ 
flush, B.1-3 
get_freellnk(), B.11-5 
getjwaiting, B.11 -6 
getJinkQ, B,11-7 
getjnksapi, B.11 -8 
getjnktei, B.11-9 
getjnktgl, B. 11-10 
get_meswaiting, B. 1 1 -1 1 
get_rlink{), B.11-12 
get_rntei, B.11 -13 
get_rsapi, B.11 -14 
get_rxstat(), B.11 -15 
get_sapi(), B.11-16 
get_sconflg (), B.11 -17 
get_sim {), B.11-18 
geMei{), B.11 -19 
getJglO, B.11-20 
getjwindow, B.11 -21 
getphy, B.1-4 
getport, B.T-6 
getime, B.1-6 
initpl, B.11-22 
inittime, B.1-7 
pi reset, B.1-8 
link_stat, B. 11-23 
pi reset, B.1-8 
receive, B.11 -24 
s_n200, B.11 -25 
S_n201, B.11-26 
s t200, B.11-27 


s_t203, B. 11-28 
set_sconfig, B. 11-29 
setjink, B.11 -30 
set_net (), B.11-31 
set_mtei, B. 11-32 
set_rsapi, B.11 -33 
set_sapi, B.11 -34 
set_sub 0. B.11 -35 
set_tei, B.11 -36 
set_tei. B.11 -37 
set_window, B.11 -38 
setfig, B.11 -39 
setleds, B.1-9 
setphy, B.1-10 
setport, B.1-11 
settimer, B.1-12 
slot 0, B.11 -40 
Sion 0, B.11-41 
srchjnk, B.11 -42 
start_sim, B. 11-43 
statusQ, B.11— 44 
timer, B.1-13 
trans, B. 11-45 
transmit , B.11 -46 
trui, B.11 -47 
trxcnl, B. 11-48 
trxidc, B. 11-49 
trxidr, B. 11-50 
trxmi , B.11-61 

mv, 2.1-25 

o 


onexit, 5.2-37 
one_block, 5.10-5 
one_error, 5.10-14 
open, 5.2-38 

Operands for CH32 configuration, 2.1-2 


P 

P1 RESET, B.1-8 
Package Description, 1.1-1 
perror, 5.2-42 
Port(s), 

AUX 1, accessing via C Shell, 5.7-1 ff. 
AUX 2, accessing via C Shell, 5.7-7ff. 
for debugger location, 2.1-1 
Selecting 
SETPORT, B.4-6 
Pri_version, B.8-2 

Primary Rate Interface Library, App. B.8 
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Pri_version, B.8-2 
SetPrimary, B.8-3 
printf, 5.2-39 

Processing of EOC Messages, B. 14-11 

putc, 5.2-43 

putchar, 5.2-44 

puts, 5.2-45 

putw, 5.2-46 

pwd, 2.1-26 

Q 

qsort, 5.2-47 


R 

rand, 5.2-48 
read, 5.2-49 
reailoc, 5.2-60 
receive, B.2-4, B.3-10. B.4-3 
B.5-3, B.7-3, B.9-4. 
B.11-24, B.12-16, 
B.13-27, B.14-10. 
recpa, 5.7-4 
rename, 5.2-51 
reset_anal, B.10-7 
reset_data, 5.10-22 
RESTARTSIM, B.3-12 
resync, 5.10-14 
rewind, 5.2-52 
rindex, 5.2-58 
rm, 2.1-27 
rmdir, 2.1-28 
rmres, 2.1-29 
run, 2.1-30 
rstdrv, 5.7-5 
Run-Time, Chapter 4.3 
System Library, 4.3-1 
Program entry/exit, 4.3-1 
Function Calls, 4.3-1 


s 

s-n200, B.3-16, B.11-25, B.12-17 
s-n201, B.3-17, B.11-26, B.12-18 
S-T200, B.3-25, B.11-27, B. 12-1 9 
S-T203, B.3-26, B.11-28, B.12-20 
scant, 5.2-53 

SDLC Library (libsdic.a), App. B5 
Functions: 


flush, B.1-3 
getphy, B.1-4 
getport, B.1-5 
getime, B, 1-6 
initpl , B.5-2 
inittime, B.1-7 
pi reset, B.1-8 
receive, B.5-3 
set-adr, B.5— 4 
set-n2, B.5-5 
set-tl, B.5-6 
set-t2, B.5-7 
setleds, B.1-9 
setphy, B.1-10 
setport, B.1-11 
settimer, B.1-12 
slot, B.5-8 
sign, B.5-9 
status, B.5-11 
timer, B.1-13 
transmit, B.5-11 
trsifr, B.5-12 
trnsi, B.5-13 
trtst, B.5-14 
trui, B.5-15 
xid, B.5-16 
sendpa, 5.7-3 
set-adr, B.5-4 
set-bit-rate, B.3-14 
set_err rate(sei), 5.10-6 
setJiniT, B. 1 1 -29, B. 1 2-22 
setjll, B.12-23 
set-mod, b.3-15 
set__mode, 5.10-7 
set— n1, B.4-4, B. 13— 28 
set— n2, B.4— 5, B.5— 6, B.13— 29 
set-net, B.3-21, B.11-30, B. 13-30 
set_pat, B.13-31 
set_pream, 5.10-7 
setjstrn, 5.10-8 
set_ratio, B. 13-32 
set— rntei, B.3— 22, B.11~61 
set-rsapi, B.3-23, B.11-32 
set-sapi, B.3-24, B.11-33 
set-sconfig, B.3-25, B. 11-34, B. 12-21 
set-sub, B.3-27 B.11-35, B.13-35 
set-tl, B.3-28, B.4-6, B.5-6, B.13-33 
set-t2, B.3-29, B.5-7, B. 13-34 
set-tei, B.3-27 B.11-36 
set-tgl, B.3-27 B.11^7 
set-window, B.3-28, B.4-7, B.11-38 
B.12-24, B.13-36 
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setbasic, B.6-3 
setbuf, 5.2-56 
setbuffer, 5.2-56 
setenv, 2.1-231 

setfig, B.2-5, B.3-13, B.11-39, B.12-25 

setjmp, 5.2-57 

setlinebuf, 5.2-56 

setleds, B.1-9 

setphy, B.1-10 

setport, B.1-11 

SetPrimary, B.8-3 

settimer, B.1-12 

SetU, B.14-1 

shell, 2.1-32 

Shutdown of U board, B. 14-1 3 
size, 2.1—33 

slot B.3-29, B.4-8, B.5-8, B:11-40, 

B. 12-26, B. 13-37 

Sion, B.3-30, B.4-9, B.5-9, B.11-41, 

B. 12-27, B. 13-38 

Specifier, U transceiver, B.14-^, -6, - 
7, -9, -10, -11, -12. 
sprintt 5.2-39 
srand, 5.2-48 
srchjnk, B. 11-42, B. 12-28 
sscanf, 5.2-53 
start_async, 5.10-9 
start_sim, B.11-43, B. 12-29 
start_sync, 5.10-10 

status, B.3— 31, B.4— 10, B.5— 11, B. 11^44, 
5.10-15 

stopsim, B.3-32 
stop_test, 5.10-15 
strcat, 5.2-58 
strcmp, 5.2-58 
strcpy, 5.2-58 
strncat, 5.2-58 
strien, 5.2-58 
strncmp, 5.2-58 
strncpy, 5.2-58 
strtol, 5.2-5 

System Library Globals, 5.3-1 

T 


2B-i-D Channel, configuring U board for, 
B.14-3 
tbreak, B.3-5 
time, 2.1-34 
timed_test, 5.10-10 
timer, B.1-13 
Timer Control (all libraries) 


Functions: 
getime, B.1-6 
fnittime, B.1-7 
settimer, B.1-12 
timer, B.1-13 
toascii, 5.2-60 
tolower, 5.2-60 
-lolower, 5.2-60 
toupper, 5.2-60 
trans, B.3-33, B.11-45, B. 12-31 
trans_resp, B 12-32 
Transceiver State, 

Get, B.14-5 
Set, B.14-5 

transmit, B.2-6, B.3-34, B.4-11, 
B.5-11, B.7-4, B.9-6, 

B.5-11, B.7-4, B.9-6, 

B.11-46, B.12-32, B.13- 
40, B.14-9 

tready, B.2-7, B.7-5, B.9-7 
trnsi, B.5-12 
trsifr, B.5-13 
trtst, B.5-14 

trui, B.3-35, B.5-15, B.11-47, B.12-34 
trxcni, B.3-36, B.11-48, B. 12-35 
trxidc, B.3-38, B.11^9, B.12-36 
trxidr, B.3-39, B.11-60, B.12-37 
trxrni, B.3-37, B.11-51, B.12-38 
Tutorial, 1 .3-1 


u__ 

U-board commands, B.14— 2 
U Library (iibu.a). Appendix B.14 
ungetc, 5.2-61 
unlink, 5.2-62 
userjstrn, 5.10-11 


V 

V.120 Library (Iibv120.a) App. B.12 
Functions 
flush, B.1-3 
getJreelinkO, B.12-4 
geMwalting, B.12-6 
get linkO, B.12-6 
getJliO, B.12-7 
getjnklli, B.12-8 
get_meswaiting, B.12-9 
get_rlink(), B. 12-10 
get_rxstat(), B. 12-11 
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get_sconfig (), B. 12-1 2 
get_wlndow, B.12-13 
getphy, B.1-4 
getport, B.1-6 
getime, B.1-6 
initpl, B. 12-1 4 
inittime, B.1-7 
link_stat B. 12-1 5 
pi reset, B.1-8 
receive, B. 12-1 6 
s_n2C0. B. 12-1 7 
s_n201. B. 12-1 8 
s_t200, B. 12-1 9 
s_t203, B.12-20 
set_sconfig, B.12-21 
setjink, B, 12-22 
setjli, B. 12-23 
set_window, B. 12-24 
setfig, B. 12-25 
setleds, B.1-9 
setphy, B.1-10 
setport, B.1-11 
settimer, B.1-12 
slot (), B.12-26 
Sion 0, B.12-27 
srchjnk, B.12-28 
start_sim, B. 12-29 
statusO, B.12-30 
timer, B.1-13 
trans, B. 12-31 
transmit , B. 12-32 
trans_resp, B. 12-33 
trui, B. 12-34 
trxcni, B. 12-35 
trxidc, B. 12-36 
trxidr, B. 12-37 
trxml , B.12-38 
Vi Editor 

Abbreviation, 6.1-15 
Append mode, 6.1-4 
Arrow keys, 6.1-3 
Autoindent ,6.1-13 
Buffer, 6.1-8 
Buffer commands: 

‘ “, 6 . 1-8 

p, 6.1-8 

P, 6.1-8 
YP, 6.1-9 
Yp, 6.1-9 

Command Reference, Section 6.2 
Control Character Table, 6.2-2 
Special Character Table, 6.2-4 


Upper Case Table, 6.2-6 
Lower Case Table, 6.2-8 
Cursor control keys: 
w, 6.1-4 

b, 6.1-4 
e, 6.1—4 
S, 6.1-8 
spacebar. 6.1-4 
backspace, 6.1-4 
G, 6.1-3 

CTRL G, 6.1-3 
6 . 1 ^ 

+, 6.1-3 
-, 6.1-3 

Delete Commands: 
d, 6.1-6 
db, 6.1-6 
dd, 6.1—6 
dL, 6.1-6 
dw, 6.1-6 

Editor options, 6.1-11 
:set, 6.1-11 
Editing commands: 
a, 6.1—4 

c, 6.1—6 
cc, 6.1—6 
cw, 6.1-6 
:e, 6.1-10 
i, 6.1-4 

o, 6.1—5 
O, 6.1-5 
X, 6.1—5 
z, 6.1-10 
CTRL H, 6.1-5 

File manipulation commands, 6.1-16 
Formfeed (CTRL L), 6.1-10 
Help, 6.1-21 
insert mode, 6.1-4 
Correction commands, 6.1-18 
Line Shifting commands: 

», 6.1-13 
«, 6.1-13 
Macro commands: 

:map, 6.1-14 
:unmap, 6.1-14 
Magic, 6.1-17 
Magic commands, 6.1-18 
Mark place, 6.1-9 
m, 6.1-9 
’,6.1-9 
6.1-9 

Parentheses (matching), 6.1-14 
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CTRL B, 6.1-2 
CTRL D, 6.1-2 
CTRL E, 6.1-2 

vi Editor Scrolling Commands 
CTRL F, 6.1-2 
CTRL U, 6.1-2 
CTRL Y, 6.1-2 
a;, 6.1-7 
f, 6.1-7 
n, 6.1-2 

t, 6.1-7 
tag, 6.1- 
^ 6.1-7 
?, 6 . 1-2 
$, 6 . 1-2 

Softkeys, 6.1-19 
Tabs; 

CTRL I, 6.1-6 
CTRL V, 6.1-8 
Text buffers, 6.1-8 
Tags {-t options), 6.1-1 
Undelete commands; 

“np, 6.1-12 
Undo commands; 

u. 6.1-7 
uu, 6.1-7 
U, 6.1-7 

Wordwrap commands; 

J, 6.1-13 
wm, 6.1-13 


W 


Window interface 
Default attributes, 5.4-2 
Escape sequences, 5.4-15 
Form mode, 5.4-1 
Functions; 
assignleds, 5.4-3 
closeform, 5.4-4 
closevt, 5.4-4 
disablecur, 5.4-6 
enablecur, 5.4-7 
getch, 5.4-8 
getcwt, 5.4-9 
openform, 5.4-10 
openvt, 5.4-11 
pmdata, 5.4—12 
putvt, 5.4-13 
selpm, 5.4—14 
Screen Attributes, 5.4-1 6 
VT100 format, 5.4-1 
write, 5.2-63 


X 


XID, B.5-21 
xtrcap, 5.2-58 
xtrcpy, 5.2-58 
xtrncpy, 5.2-58 
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